@wakastellar/ui 3.5.2 → 4.0.0

package/src/components/waka-doc-toc/WakaDocToc.mdx

@@ -0,0 +1,73 @@
+import { Meta, Canvas, Controls, Source, ArgTypes } from '@storybook/addon-docs/blocks'
+import * as Stories from './WakaDocToc.stories'
+
+<Meta of={Stories} />
+
+# WakaDocToc
+
+Table-of-contents sidebar driven by an IntersectionObserver to highlight the active section.
+
+## Installation
+
+The component is exported from the root entry point of `@wakastellar/ui`:
+
+<Source language="tsx" code={`import { WakaDocToc } from '@wakastellar/ui'`} />
+
+If you use the CLI scaffolder:
+
+<Source language="bash" code={`npx wakastellar-ui add waka-doc-toc`} />
+
+## Usage
+
+<Canvas of={Stories.Default} />
+
+<Controls of={Stories.Default} />
+
+## Examples
+
+### Deep Nesting
+
+<Canvas of={Stories.DeepNesting} />
+
+### Short
+
+<Canvas of={Stories.Short} />
+
+### Long
+
+<Canvas of={Stories.Long} />
+
+### Controlled
+
+<Canvas of={Stories.Controlled} />
+
+### Inline
+
+<Canvas of={Stories.Inline} />
+
+
+## API Reference
+
+<ArgTypes of={Stories.Default} />
+
+## Accessibility
+
+- Full keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys where applicable).
+- Compatible with screen readers via Radix UI primitives.
+- Focus ring visible at all times; never `outline: none` without a replacement.
+- Color contrast meets WCAG AA in both light and dark themes.
+
+## Theming
+
+All visual tokens are CSS custom properties consumed via Tailwind v4. Override
+in your app's `globals.css` to customize:
+
+<Source language="css" code={`:root {
+  --primary: oklch(0.65 0.18 250);
+  --primary-foreground: oklch(0.98 0 0);
+}`} />
+
+## Related
+
+- See the audit fiche: \`docs/audit/components/waka-doc-toc.md\`
+- See the [accessibility dimension report](?path=/docs/dimensions-accessibility--docs)

package/src/components/waka-doc-toc/WakaDocToc.stories.tsx

@@ -13,7 +13,6 @@ const meta: Meta<typeof WakaDocToc> = {
       },
     },
   },
-  tags: ['autodocs'],
 }
 
 export default meta
@@ -35,20 +34,95 @@ const sampleItems = [
 export const Default: Story = {
   args: {
     items: sampleItems,
-    activeId: 'configuration',
+    activeId: "configuration",
   },
+  render: (args) => <WakaDocToc {...args} />,
 }
 
 export const DeepNesting: Story = {
   args: {
     items: [
-      { id: 'overview', text: 'Overview', level: 2 },
-      { id: 'architecture', text: 'Architecture', level: 3 },
-      { id: 'components', text: 'Components', level: 4 },
-      { id: 'hooks', text: 'Hooks', level: 4 },
-      { id: 'setup', text: 'Setup', level: 2 },
-      { id: 'prerequisites', text: 'Prerequisites', level: 3 },
-    ],
-    activeId: 'components',
+        { id: 'overview', text: 'Overview', level: 2 },
+        { id: 'architecture', text: 'Architecture', level: 3 },
+        { id: 'components', text: 'Components', level: 4 },
+        { id: 'hooks', text: 'Hooks', level: 4 },
+        { id: 'setup', text: 'Setup', level: 2 },
+        { id: 'prerequisites', text: 'Prerequisites', level: 3 },
+      ],
+    activeId: "components",
   },
+  render: (args) => <WakaDocToc {...args} />,
+}
+
+export const Short: Story = {
+  args: {
+    items: [
+        { id: 'intro', text: 'Introduction', level: 2 },
+        { id: 'usage', text: 'Usage', level: 2 },
+        { id: 'api', text: 'API', level: 2 },
+      ],
+    activeId: "usage",
+  },
+  render: (args) => <WakaDocToc {...args} />,
+}
+
+export const Long: Story = {
+  args: {
+    items: Array.from({ length: 14 }).flatMap((_, idx) => [
+        { id: `section-${idx}`, text: `Section ${idx + 1}`, level: 2 as const },
+        { id: `section-${idx}-detail-a`, text: 'Background', level: 3 as const },
+        { id: `section-${idx}-detail-b`, text: 'Implementation', level: 3 as const },
+      ]),
+    activeId: "section-3-detail-a",
+  },
+  render: (args) => <WakaDocToc {...args} />,
+}
+
+export const Controlled: Story = {
+  render: function ControlledToc() {
+    const [activeId, setActiveId] = React.useState('configuration')
+    const items = sampleItems
+    return (
+      <div className="space-y-3">
+        <WakaDocToc items={items} activeId={activeId} />
+        <div className="flex justify-center gap-2 text-xs">
+          {items.slice(0, 4).map((it) => (
+            <button
+              key={it.id}
+              type="button"
+              className="rounded border px-2 py-1 hover:bg-muted"
+              onClick={() => setActiveId(it.id)}
+            >
+              {it.text}
+            </button>
+          ))}
+        </div>
+      </div>
+    )
+  },
+}
+
+export const Inline: Story = {
+  render: () => (
+    <div className="grid grid-cols-[1fr_220px] gap-6 max-w-3xl">
+      <article className="prose">
+        <h2>Getting Started</h2>
+        <p>Read the sections on the right to navigate the page.</p>
+        <h3>Installation</h3>
+        <p>Install the package via your favourite package manager.</p>
+        <h3>Configuration</h3>
+        <p>Customise the renderer to match your design system.</p>
+      </article>
+      <aside className="sticky top-4 self-start">
+        <WakaDocToc
+          items={[
+            { id: 'getting-started', text: 'Getting Started', level: 2 },
+            { id: 'installation', text: 'Installation', level: 3 },
+            { id: 'configuration', text: 'Configuration', level: 3 },
+          ]}
+          activeId="installation"
+        />
+      </aside>
+    </div>
+  ),
 }

package/src/components/waka-doc-toolbar/WakaDocToolbar.mdx

@@ -0,0 +1,75 @@
+import { Meta, Canvas, Controls, Source, ArgTypes } from '@storybook/addon-docs/blocks'
+import * as Stories from './WakaDocToolbar.stories'
+
+<Meta of={Stories} />
+
+# WakaDocToolbar
+
+Toolbar bar for the WakaDoc renderer; hosts share, edit, and export actions.
+
+> ⚠️ **Composant en refactor.** Ce composant est marqué `refactor` dans l'audit (cf. `docs/audit/components/waka-doc-toolbar.md`). Il pourra être fusionné, scindé ou déplacé dans un sous-projet futur ; vérifiez la fiche d'audit avant tout usage massif.
+
+## Installation
+
+The component is exported from the root entry point of `@wakastellar/ui`:
+
+<Source language="tsx" code={`import { WakaDocToolbar } from '@wakastellar/ui'`} />
+
+If you use the CLI scaffolder:
+
+<Source language="bash" code={`npx wakastellar-ui add waka-doc-toolbar`} />
+
+## Usage
+
+<Canvas of={Stories.ViewMode} />
+
+<Controls of={Stories.ViewMode} />
+
+## Examples
+
+### Editable View Mode
+
+<Canvas of={Stories.EditableViewMode} />
+
+### Edit Mode
+
+<Canvas of={Stories.EditMode} />
+
+### Saving
+
+<Canvas of={Stories.Saving} />
+
+### Saved
+
+<Canvas of={Stories.Saved} />
+
+### Save Error
+
+<Canvas of={Stories.SaveError} />
+
+
+## API Reference
+
+<ArgTypes of={Stories.ViewMode} />
+
+## Accessibility
+
+- Full keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys where applicable).
+- Compatible with screen readers via Radix UI primitives.
+- Focus ring visible at all times; never `outline: none` without a replacement.
+- Color contrast meets WCAG AA in both light and dark themes.
+
+## Theming
+
+All visual tokens are CSS custom properties consumed via Tailwind v4. Override
+in your app's `globals.css` to customize:
+
+<Source language="css" code={`:root {
+  --primary: oklch(0.65 0.18 250);
+  --primary-foreground: oklch(0.98 0 0);
+}`} />
+
+## Related
+
+- See the audit fiche: \`docs/audit/components/waka-doc-toolbar.md\`
+- See the [accessibility dimension report](?path=/docs/dimensions-accessibility--docs)

package/src/components/waka-doc-toolbar/WakaDocToolbar.stories.tsx

@@ -13,7 +13,6 @@ const meta: Meta<typeof WakaDocToolbar> = {
       },
     },
   },
-  tags: ['autodocs'],
   argTypes: {
     mode: { control: 'select', options: ['view', 'edit'] },
     canEdit: { control: 'boolean' },
@@ -77,3 +76,16 @@ export const SaveError: Story = {
     saveStatus: 'error',
   },
 }
+
+/**
+ * Playground — generated to make the Storybook Controls panel functional.
+ * Exposes a default arg set wired to the component via {...args}.
+ */
+export const Playground: Story = {
+  args: {
+    mode: "view",
+    canEdit: false,
+    saveStatus: "idle",
+  },
+  render: (args) => <WakaDocToolbar {...args} />,
+}

package/src/components/waka-doc-toolbar/index.tsx

@@ -27,6 +27,11 @@ export interface WakaDocToolbarProps {
   className?: string
 }
 
+/**
+ * @deprecated Since v3.6 — will be removed in v4.0.
+ * Use the `@wakastellar/ui-docs` sub-package (`<DocToolbar>` with shared provider) instead.
+ * See `docs/audit/remove-relocate.md` §2.2.
+ */
 export function WakaDocToolbar({
   content,
   mode = "view",

package/src/components/waka-doc-version/WakaDocVersion.mdx

@@ -0,0 +1,73 @@
+import { Meta, Canvas, Controls, Source, ArgTypes } from '@storybook/addon-docs/blocks'
+import * as Stories from './WakaDocVersion.stories'
+
+<Meta of={Stories} />
+
+# WakaDocVersion
+
+Version switcher for documentation; supports semver tags and "latest" alias.
+
+## Installation
+
+The component is exported from the root entry point of `@wakastellar/ui`:
+
+<Source language="tsx" code={`import { WakaDocVersion } from '@wakastellar/ui'`} />
+
+If you use the CLI scaffolder:
+
+<Source language="bash" code={`npx wakastellar-ui add waka-doc-version`} />
+
+## Usage
+
+<Canvas of={Stories.Default} />
+
+<Controls of={Stories.Default} />
+
+## Examples
+
+### Stable Selected
+
+<Canvas of={Stories.StableSelected} />
+
+### Viewing Deprecated
+
+<Canvas of={Stories.ViewingDeprecated} />
+
+### Many Versions
+
+<Canvas of={Stories.ManyVersions} />
+
+### Two Versions
+
+<Canvas of={Stories.TwoVersions} />
+
+### RC
+
+<Canvas of={Stories.RC} />
+
+
+## API Reference
+
+<ArgTypes of={Stories.Default} />
+
+## Accessibility
+
+- Full keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys where applicable).
+- Compatible with screen readers via Radix UI primitives.
+- Focus ring visible at all times; never `outline: none` without a replacement.
+- Color contrast meets WCAG AA in both light and dark themes.
+
+## Theming
+
+All visual tokens are CSS custom properties consumed via Tailwind v4. Override
+in your app's `globals.css` to customize:
+
+<Source language="css" code={`:root {
+  --primary: oklch(0.65 0.18 250);
+  --primary-foreground: oklch(0.98 0 0);
+}`} />
+
+## Related
+
+- See the audit fiche: \`docs/audit/components/waka-doc-version.md\`
+- See the [accessibility dimension report](?path=/docs/dimensions-accessibility--docs)

package/src/components/waka-doc-version/WakaDocVersion.stories.tsx

@@ -13,7 +13,6 @@ const meta: Meta<typeof WakaDocVersion> = {
       },
     },
   },
-  tags: ['autodocs'],
 }
 
 export default meta
@@ -39,3 +38,89 @@ export const Default: Story = {
     )
   },
 }
+
+export const StableSelected: Story = {
+  render: function StableSelectedDemo() {
+    const [current, setCurrent] = React.useState('v3.1.0')
+    return (
+      <WakaDocVersion
+        versions={versions}
+        current={current}
+        onVersionChange={setCurrent}
+      />
+    )
+  },
+}
+
+export const ViewingDeprecated: Story = {
+  render: function DeprecatedDemo() {
+    const [current, setCurrent] = React.useState('v2.5.0')
+    return (
+      <div className="space-y-2">
+        <WakaDocVersion
+          versions={versions}
+          current={current}
+          onVersionChange={setCurrent}
+        />
+        <p className="text-xs text-amber-600">
+          You are reading the documentation for a deprecated version.
+        </p>
+      </div>
+    )
+  },
+}
+
+export const ManyVersions: Story = {
+  render: function ManyVersionsDemo() {
+    const long = Array.from({ length: 12 }).map((_, i) => ({
+      id: `v3.${i}.0`,
+      label: `v3.${i}.0`,
+      status: i === 11 ? ('latest' as const) : i >= 9 ? ('stable' as const) : undefined,
+    }))
+    const [current, setCurrent] = React.useState('v3.11.0')
+    return (
+      <WakaDocVersion versions={long} current={current} onVersionChange={setCurrent} />
+    )
+  },
+}
+
+export const TwoVersions: Story = {
+  render: function TwoVersionsDemo() {
+    const [current, setCurrent] = React.useState('v1.0.0')
+    return (
+      <WakaDocVersion
+        versions={[
+          { id: 'v1.0.0', label: 'v1.0.0', status: 'latest' },
+          { id: 'v0.9.0', label: 'v0.9.0', status: 'stable' },
+        ]}
+        current={current}
+        onVersionChange={setCurrent}
+      />
+    )
+  },
+}
+
+export const RC: Story = {
+  render: function RCDemo() {
+    const [current, setCurrent] = React.useState('v5.0.0-rc.1')
+    return (
+      <WakaDocVersion
+        versions={[
+          { id: 'v5.0.0-rc.1', label: 'v5.0.0-rc.1', status: 'rc' },
+          { id: 'v4.0.0', label: 'v4.0.0', status: 'latest' },
+          { id: 'v3.1.0', label: 'v3.1.0', status: 'stable' },
+        ]}
+        current={current}
+        onVersionChange={setCurrent}
+      />
+    )
+  },
+}
+
+/**
+ * Playground — generated to make the Storybook Controls panel functional.
+ * Exposes a default arg set wired to the component via {...args}.
+ */
+export const Playground: Story = {
+  render: (args) => <WakaDocVersion {...args} />,
+}

package/src/components/waka-dock/WakaDock.mdx

@@ -0,0 +1,95 @@
+import { Meta, Canvas, Controls, Source, ArgTypes } from '@storybook/addon-docs/blocks'
+import * as Stories from './WakaDock.stories'
+
+<Meta of={Stories} />
+
+# WakaDock
+
+macOS-style dock with magnification on hover; useful for command palettes and toolbars.
+
+> ⚠️ **Composant en refactor.** Ce composant est marqué `refactor` dans l'audit (cf. `docs/audit/components/waka-dock.md`). Il pourra être fusionné, scindé ou déplacé dans un sous-projet futur ; vérifiez la fiche d'audit avant tout usage massif.
+
+## Installation
+
+The component is exported from the root entry point of `@wakastellar/ui`:
+
+<Source language="tsx" code={`import { WakaDock } from '@wakastellar/ui'`} />
+
+If you use the CLI scaffolder:
+
+<Source language="bash" code={`npx wakastellar-ui add waka-dock`} />
+
+## Usage
+
+<Canvas of={Stories.Default} />
+
+<Controls of={Stories.Default} />
+
+## Examples
+
+### Positions
+
+<Canvas of={Stories.Positions} />
+
+### Sizes
+
+<Canvas of={Stories.Sizes} />
+
+### With Badges
+
+<Canvas of={Stories.WithBadges} />
+
+### With Active Indicator
+
+<Canvas of={Stories.WithActiveIndicator} />
+
+### Mac OS Style
+
+<Canvas of={Stories.MacOSStyle} />
+
+### Vertical Dock
+
+<Canvas of={Stories.VerticalDock} />
+
+### No Labels
+
+<Canvas of={Stories.NoLabels} />
+
+### Magnification Settings
+
+<Canvas of={Stories.MagnificationSettings} />
+
+### App Dock With Sections
+
+<Canvas of={Stories.AppDockWithSections} />
+
+### Dark Mode
+
+<Canvas of={Stories.DarkMode} />
+
+
+## API Reference
+
+<ArgTypes of={Stories.Default} />
+
+## Accessibility
+
+- Full keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys where applicable).
+- Compatible with screen readers via Radix UI primitives.
+- Focus ring visible at all times; never `outline: none` without a replacement.
+- Color contrast meets WCAG AA in both light and dark themes.
+
+## Theming
+
+All visual tokens are CSS custom properties consumed via Tailwind v4. Override
+in your app's `globals.css` to customize:
+
+<Source language="css" code={`:root {
+  --primary: oklch(0.65 0.18 250);
+  --primary-foreground: oklch(0.98 0 0);
+}`} />
+
+## Related
+
+- See the audit fiche: \`docs/audit/components/waka-dock.md\`
+- See the [accessibility dimension report](?path=/docs/dimensions-accessibility--docs)

package/src/components/waka-dock/WakaDock.stories.tsx

@@ -31,7 +31,6 @@ const meta: Meta<typeof WakaDock> = {
       },
     },
   },
-  tags: ['autodocs'],
   argTypes: {
     position: {
       control: 'select',
@@ -330,3 +329,17 @@ export const DarkMode: Story = {
     </div>
   ),
 }
+
+/**
+ * Playground — generated to make the Storybook Controls panel functional.
+ * Exposes a default arg set wired to the component via {...args}.
+ */
+export const Playground: Story = {
+  args: {
+    position: "bottom",
+    size: "sm",
+    showLabels: false,
+    fixed: false,
+  },
+  render: (args) => <WakaDock {...args} />,
+}

package/src/components/waka-dock/index.tsx

@@ -40,6 +40,11 @@ export interface WakaDockProps {
 // Component
 // ============================================================================
 
+/**
+ * @deprecated Since v3.6 — will be removed in v4.0.
+ * Use the `@wakastellar/ui-docs` sub-package (`<DocDock>` with shared provider) instead.
+ * See `docs/audit/remove-relocate.md` §2.2.
+ */
 export function WakaDock({
   items,
   position = "bottom",
@@ -153,6 +158,7 @@ export function WakaDock({
 
             {/* Dock Item */}
             <button
+              type="button"
               onClick={item.onClick}
               className={cn(
                 "relative flex items-center justify-center rounded-xl transition-all duration-150",

package/src/components/waka-drawer/WakaDrawer.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas, Controls, Source, ArgTypes } from '@storybook/addon-docs/blocks'
+import * as Stories from './WakaDrawer.stories'
+
+<Meta of={Stories} />
+
+# WakaDrawer
+
+Side drawer with focus trap and ESC dismissal; built on top of Radix Dialog.
+
+## Installation
+
+The component is exported from the root entry point of `@wakastellar/ui`:
+
+<Source language="tsx" code={`import { WakaDrawer } from '@wakastellar/ui'`} />
+
+If you use the CLI scaffolder:
+
+<Source language="bash" code={`npx wakastellar-ui add waka-drawer`} />
+
+## Usage
+
+<Canvas of={Stories.Default} />
+
+<Controls of={Stories.Default} />
+
+## Examples
+
+### Positions
+
+<Canvas of={Stories.Positions} />
+
+### Sizes
+
+<Canvas of={Stories.Sizes} />
+
+### With Footer
+
+<Canvas of={Stories.WithFooter} />
+
+### Navigation Menu
+
+<Canvas of={Stories.NavigationMenu} />
+
+### Filter Panel
+
+<Canvas of={Stories.FilterPanel} />
+
+### With Hook
+
+<Canvas of={Stories.WithHook} />
+
+### No Overlay
+
+<Canvas of={Stories.NoOverlay} />
+
+### Custom Content
+
+<Canvas of={Stories.CustomContent} />
+
+
+## API Reference
+
+<ArgTypes of={Stories.Default} />
+
+## Accessibility
+
+- Full keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys where applicable).
+- Compatible with screen readers via Radix UI primitives.
+- Focus ring visible at all times; never `outline: none` without a replacement.
+- Color contrast meets WCAG AA in both light and dark themes.
+
+## Theming
+
+All visual tokens are CSS custom properties consumed via Tailwind v4. Override
+in your app's `globals.css` to customize:
+
+<Source language="css" code={`:root {
+  --primary: oklch(0.65 0.18 250);
+  --primary-foreground: oklch(0.98 0 0);
+}`} />
+
+## Related
+
+- See the audit fiche: \`docs/audit/components/waka-drawer.md\`
+- See the [accessibility dimension report](?path=/docs/dimensions-accessibility--docs)