Skip to content

[Feature]: Promote storybook to Stable — settle the helper surface #148

Description

@JosunLP

Pre-flight checklist

  • I searched existing issues and did not find a duplicate request.
  • I explained the problem or use case, not just the desired API.

Problem or use case
storybook is Beta (it's not in the issue form's area dropdown, so this is filed under "other"). It's a helper-only entry point — storyHtml, when, plus the 1.14.0 additions classMap, styleMap, ifDefined, repeat, and unsafeHtml — and those template helpers are one minor old. Teams writing stories against these helpers need a frozen surface, and unsafeHtml in particular needs its security contract pinned down given bQuery's secure-by-default stance.

Proposed solution
Freeze the storybook helper API for one cycle, document each helper (especially the safety boundary of unsafeHtml and how it interacts with the security module's sanitizer), and add coverage for the template helpers' output. Exit criteria: frozen surface, documented helpers with unsafeHtml security guidance, tested rendering output.

Possible API or UX shape

import { storyHtml, classMap, ifDefined, repeat } from "@bquery/bquery/storybook";

export const Default = storyHtml`
  <my-card class=${classMap({ active: true })} title=${ifDefined(title)}>
    ${repeat(items, i => i.id, i => storyHtml`<li>${i.label}</li>`)}
  </my-card>
`;

Alternatives considered
Leaving it Beta as a "minor helper module" — but it's part of the stated road-to-stable for all modules, and its unsafeHtml helper has a security dimension that warrants a pinned contract. Folding it into testing — different purpose (authoring stories vs. assertions), so keep it separate.

Relevant area
other

Additional context
Filed as other because storybook is absent from the area dropdown — flag to maintainers whether the dropdown should add a storybook option. The unsafeHtml boundary should be defined in terms of the existing security/sanitizer module.

Metadata

Metadata

Assignees

No one assigned

    Labels

    storybookChanges to the storybook module

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions