@waggylabs/yumekit 0.5.1-beta.8 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/CHANGELOG.md +61 -35
  2. package/CONTRIBUTING.md +16 -3
  3. package/README.md +63 -42
  4. package/dist/ai/llm.txt +2194 -0
  5. package/dist/ai/skill/SKILL.md +41 -0
  6. package/dist/ai/skill/examples/form.html +59 -0
  7. package/dist/ai/skill/examples/nav-layout.html +82 -0
  8. package/dist/ai/skill/examples/themed-app.html +120 -0
  9. package/dist/ai/skill/patterns.md +377 -0
  10. package/dist/ai/skill/reference.md +2040 -0
  11. package/dist/components/y-appbar.js +132 -38
  12. package/dist/components/y-banner.js +10 -8
  13. package/dist/components/y-button.js +10 -8
  14. package/dist/components/y-code/y-code.d.ts +4 -0
  15. package/dist/components/y-code.d.ts +4 -0
  16. package/dist/components/y-code.js +96 -3
  17. package/dist/components/y-color.js +16 -2
  18. package/dist/components/y-colorpicker.js +16 -2
  19. package/dist/components/y-data-grid/y-data-grid.d.ts +8 -0
  20. package/dist/components/y-data-grid.d.ts +8 -0
  21. package/dist/components/y-data-grid.js +221 -65
  22. package/dist/components/y-date.js +582 -47
  23. package/dist/components/y-datepicker/y-datepicker.d.ts +9 -0
  24. package/dist/components/y-datepicker.d.ts +9 -0
  25. package/dist/components/y-datepicker.js +582 -47
  26. package/dist/components/y-dock/y-dock.d.ts +3 -0
  27. package/dist/components/y-dock.d.ts +3 -0
  28. package/dist/components/y-dock.js +43 -4
  29. package/dist/components/y-drawer.js +4 -1
  30. package/dist/components/y-help.js +13 -19
  31. package/dist/components/y-menu/y-menu.d.ts +1 -0
  32. package/dist/components/y-menu.d.ts +1 -0
  33. package/dist/components/y-menu.js +107 -25
  34. package/dist/components/y-paginator.js +26 -10
  35. package/dist/components/y-popover.js +2 -10
  36. package/dist/components/y-select.js +16 -2
  37. package/dist/components/y-sidebar/y-sidebar.d.ts +9 -0
  38. package/dist/components/y-sidebar.d.ts +9 -0
  39. package/dist/components/y-sidebar.js +141 -34
  40. package/dist/components/y-switch.js +19 -4
  41. package/dist/components/y-theme/y-theme.d.ts +8 -1
  42. package/dist/components/y-theme.d.ts +8 -1
  43. package/dist/components/y-theme.js +106 -51
  44. package/dist/index.js +658 -158
  45. package/dist/modules/helpers.d.ts +14 -0
  46. package/dist/modules/helpers.js +24 -0
  47. package/dist/modules/helpers.test.js +46 -0
  48. package/dist/react.d.ts +13 -0
  49. package/dist/styles/blue-dark.css +4 -0
  50. package/dist/styles/blue-light.css +4 -0
  51. package/dist/styles/brown-dark.css +4 -0
  52. package/dist/styles/brown-light.css +4 -0
  53. package/dist/styles/catppuccin-frappe.css +4 -0
  54. package/dist/styles/catppuccin-latte.css +4 -0
  55. package/dist/styles/catppuccin-macchiato.css +4 -0
  56. package/dist/styles/catppuccin-mocha.css +4 -0
  57. package/dist/styles/green-dark.css +4 -0
  58. package/dist/styles/green-light.css +4 -0
  59. package/dist/styles/indigo-dark.css +4 -0
  60. package/dist/styles/indigo-light.css +4 -0
  61. package/dist/styles/kepler-amber.css +224 -0
  62. package/dist/styles/kepler-dark.css +224 -0
  63. package/dist/styles/kepler-galaxy.css +224 -0
  64. package/dist/styles/kepler-light.css +224 -0
  65. package/dist/styles/kepler-matrix.css +224 -0
  66. package/dist/styles/material-blue-dark.css +3 -3
  67. package/dist/styles/material-blue-light.css +3 -3
  68. package/dist/styles/material-purple-dark.css +3 -3
  69. package/dist/styles/material-purple-light.css +3 -3
  70. package/dist/styles/mono-dark.css +4 -0
  71. package/dist/styles/mono-light.css +4 -0
  72. package/dist/styles/nord-aurora.css +4 -0
  73. package/dist/styles/nord.css +4 -0
  74. package/dist/styles/olive-dark.css +4 -0
  75. package/dist/styles/olive-light.css +4 -0
  76. package/dist/styles/orange-dark.css +4 -0
  77. package/dist/styles/orange-light.css +4 -0
  78. package/dist/styles/pink-dark.css +4 -0
  79. package/dist/styles/pink-light.css +4 -0
  80. package/dist/styles/purple-dark.css +4 -0
  81. package/dist/styles/purple-light.css +4 -0
  82. package/dist/styles/red-dark.css +4 -0
  83. package/dist/styles/red-light.css +4 -0
  84. package/dist/styles/rose-dark.css +4 -0
  85. package/dist/styles/rose-light.css +4 -0
  86. package/dist/styles/slate-dark.css +219 -0
  87. package/dist/styles/slate-light.css +219 -0
  88. package/dist/styles/teal-dark.css +4 -0
  89. package/dist/styles/teal-light.css +4 -0
  90. package/dist/styles/variables.css +42 -1
  91. package/dist/styles/{neobrutalist-dark.css → waggy-dark.css} +4 -2
  92. package/dist/styles/{neobrutalist.css → waggy.css} +4 -2
  93. package/dist/styles/yellow-dark.css +4 -0
  94. package/dist/styles/yellow-light.css +4 -0
  95. package/dist/yumekit.min.js +1 -1
  96. package/llm.txt +47 -17
  97. package/package.json +11 -4
  98. package/scripts/install-ai-docs.js +117 -0
package/CHANGELOG.md CHANGED
@@ -31,81 +31,107 @@ Delete any empty sections before publishing.
31
31
  <!-- ### Security -->
32
32
  <!-- Vulnerability patches or hardening changes -->
33
33
 
34
- ## [0.5.1]
34
+ ## [0.5.1] - 2026-06-20
35
35
 
36
36
  ### Added
37
37
 
38
- - `y-checkbox` / `y-radio` — checked-state color hooks so themes can fill the control on selection: `--component-checkbox-checked-background` / `-checked-border-color` / `-checked-icon-color` and `--component-radio-background` / `-checked-background` / `-checked-border-color` / `-checked-dot-color`. Each falls back to the matching unchecked value, so existing themes are unchanged. The design-system themes now use them — checked checkboxes (and Shadcn/Bootstrap/Primer radios) fill with the primary color and draw the check/dot in the primary-inverse color, matching each system's native look.
38
+ - New `y-data-grid` component — interactive grid for large datasets with client- or server-side sorting, filtering, and pagination, row selection, inline cell editing, grouping with aggregates, multi-column header groups, virtual scrolling, a per-column header menu, and a sticky header.
39
39
 
40
- - Several theme color variations including the `Catppuccin` and `Nord` color schemes, two `Rose` color themes, two `Neobrutalist` themes, as well as several new themes based on some of the most popular design systems. This includes Material, Carbon, Ant, Shadcn, Primer, and Bootstrap.
40
+ - New `y-popover` component — anchored floating panel with slotted content, composable triggers (`click` / `hover` / `focus` / `context-menu` / `manual`), flip-on-collision positioning, optional modal mode with focus trap, and a `portal` mode that renders into the nearest enclosing `<y-theme>` (falling back to `<body>`).
41
41
 
42
- - `y-tabs` — new `variant="accent"` style: minimal tabs where the active tab shows a primary-colored indicator border on its content-facing edge (bottom for top tabs, etc.). The default bordered style is unchanged. Adds `--component-tabs-accent-width` (indicator thickness). The border-width token is normalized to `--component-tabs-border-width` (matching `--component-tabs-border-color`); the legacy `--component-tab-border-width` is still honored as a fallback.
42
+ - New `y-help` component — guided product-tour overlay with ordered steps, a dimmed SVG highlight, anchored tooltip, prev/next controls, and keyboard shortcuts.
43
43
 
44
- - Form fields (`y-input`, `y-textarea`, `y-select`, `y-color`, `y-date`) — new `variant="underline"` style: a bottom-only border with square bottom corners (the Material/Carbon text-field look) instead of the full-border `"default"`. Hover/focus/invalid states still color the underline. Helps match design systems that use underlined fields.
44
+ - New `y-code` component — code block with line numbers, copy-to-clipboard (block and per-line), `max-lines` collapse, and an optional filename header. Built-in tokenizer covers JavaScript, TypeScript, JSON, CSS, Python, Bash, and HTML and emits Prism-compatible classes; an external highlighter can feed the sanitized `highlighted` slot.
45
45
 
46
- - New `y-data-grid` component — interactive grid for large or dynamic datasets with client- or server-side sorting, filtering, and pagination, single/multi row selection, inline cell editing, nested row grouping with aggregates, multi-column header groups, virtual scrolling, an optional per-column header menu (filter, sort, visibility, reorder), and a sticky header.
46
+ - New `y-shape` component — clips slotted content into a geometric shape (rectangle, circle, ellipse, star, heart, chat-bubble, times, cross, or custom `polygon`) via CSS `clip-path`.
47
47
 
48
- - New `y-popover` component — target-anchored floating panel with rich slotted content, composable triggers (`click` / `hover` / `focus` / `context-menu` / `manual`), flip-on-collision positioning, optional modal mode with focus trap, and an opt-in `portal` mode that renders into `<body>` to escape ancestor stacking contexts.
48
+ - Many new themes: `Slate`, `Rose`, `Catppuccin`, and `Nord`. We also added two `Waggy` themes, several themes based on other open source design systems (Material, Carbon, Ant, Shadcn, Primer, Bootstrap). We also added `Kepler` themes in a nod to Kepler UI, YumeKit's spiritual predecessor.
49
49
 
50
- - New `y-help` component — guided product-tour / onboarding overlay. Walks users through an ordered list of steps with a dimmed SVG highlight, anchored tooltip, prev/next controls, overlay-edge arrows, and keyboard shortcuts.
50
+ - Filled icon variants for `y-icon` via a new `weight="filled"` value, falling back to the line icon when no filled version is registered. 116 filled icons ship under `icons/all-filled.js` (also pulled in by `icons/all.js`).
51
51
 
52
- - New `y-code` component — code-block container with line numbers, copy-to-clipboard (block and per-line), `max-lines` collapse, and an optional filename header. Built-in tokenizer covers JavaScript, TypeScript, JSON, CSS, Python, Bash, and HTML; emits Prism-compatible classes so existing Prism stylesheets layer on cleanly, or pipe an external highlighter's output through the sanitized `highlighted` slot.
52
+ - AI assistant docs now ship with the package, plus an `npx @waggylabs/yumekit init-ai` command that installs the YumeKit Claude Code skill (`.claude/skills/yumekit/`), `llm.txt`, and an `AGENTS.md` pointer. Opt-in and idempotent; skips existing files unless `--force` is passed.
53
53
 
54
- - New `y-shape` component — presentational container that clips its slotted content into a geometric shape (rectangle, circle, ellipse, star, heart, chat-bubble, times, cross, or a custom `polygon`) via CSS `clip-path`. Suitable for avatar masks, decorative panels, and non-rectangular skeletons.
54
+ - `y-checkbox` / `y-radio` — checked-state color hooks so themes can fill the control on selection: `--component-checkbox-checked-background` / `-checked-border-color` / `-checked-icon-color` and `--component-radio-background` / `-checked-background` / `-checked-border-color` / `-checked-dot-color`. Each falls back to its unchecked value. The design-system themes use them to fill checked controls with the primary color.
55
55
 
56
- - `y-stepper` — `responsive` and `responsive-breakpoint` attributes; auto-flips horizontal layouts to vertical below the breakpoint (600px default). Enabled by default; set `responsive="false"` to opt out.
56
+ - `y-tabs` — new `variant="accent"` style: the active tab shows a primary-colored indicator on its content-facing edge. Adds `--component-tabs-accent-width` (indicator thickness) and normalizes the border-width token to `--component-tabs-border-width` (legacy `--component-tab-border-width` still honored).
57
57
 
58
- - Filled icon variants for `y-icon` via a new `weight="filled"` value, with automatic fallback to the line icon when no filled version is registered. 116 filled icons ship under `icons/all-filled.js` (also pulled in by `icons/all.js`); the remaining component-illustration icons fall back to their line versions.
58
+ - Form fields (`y-input`, `y-textarea`, `y-select`, `y-color`, `y-date`) — new `variant="underline"` style: a bottom-only border with square bottom corners. Hover/focus/invalid states still color the underline.
59
59
 
60
- - New theming hooks: `--component-control-height-{size}` (shared min-height for `y-button` and `y-input` so fields and buttons match per theme, falling back to `--sizing-{size}`), `--component-checkbox-border-radius` (lets checkboxes use a tighter radius than text inputs). Outlined `y-button`s now source their border from the matching semantic border token (`--base-border`, `--error-border`, …) per color, falling back to the button's text color when that token is unset; `--component-button-outline-border` / `--component-button-outline-border-color` remain available as optional global overrides. Defaults preserve the existing look for all current themes.
60
+ - `y-dock` — new `floating` attribute that detaches the dock into a bordered, rounded island inset from the viewport edges with a drop shadow. Tunable via `--component-dock-border-radius`, `--component-dock-floating-margin`, and `--component-dock-shadow`.
61
+
62
+ - New theming hooks: `--component-control-height-{size}` (shared min-height for `y-button` and `y-input`, falling back to `--sizing-{size}`) and `--component-checkbox-border-radius` (tighter checkbox radius). Outlined `y-button`s now source their border from the matching semantic border token per color, falling back to the text color; `--component-button-outline-border` / `--component-button-outline-border-color` remain as global overrides.
63
+
64
+ - `y-stepper` — new `responsive` and `responsive-breakpoint` attributes; auto-flips horizontal layouts to vertical below the breakpoint (600px default). Set `responsive="false"` to opt out.
61
65
 
62
66
  ### Changed
63
67
 
64
- - `y-break` — the divider line now uses the semantic border color (`base.border`) instead of `base.content.lightest`, matching other component borders, and the host now applies default perpendicular spacing (above/below a horizontal break, left/right of a vertical one) via the new `--component-break-spacing` token (defaults to `--spacing-medium`) so a break separates content out of the box. The line color and thickness also gained `--base-border` / `1px` fallbacks for use without a full token set.
68
+ - **Breaking** `y-break` — `inset` values renamed from `"sm"` / `"md"` / `"lg"` to `"small"` / `"medium"` / `"large"` to match the size scale used elsewhere. Spacing is unchanged, so output is identical after the rename.
69
+
70
+ - Custom color support expanded to the browser-native color functions — `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, and `color()` — alongside `#hex`, `rgb()`/`rgba()`, and `hsl()`/`hsla()`. The `isSafeCssColor` gate also tightens its allowlist, rejecting semicolons, braces, angle brackets, and nested functions. Applies anywhere a `color` accepts a custom value.
71
+
72
+ - Every bordered component now applies its `--component-*-border-width` token as the `border-width` longhand, so each accepts a 1–4 value pattern for per-side borders. Covers surfaces (`y-card`, `y-menu`, `y-dialog`, `y-popover`, `y-datepicker`, `y-data-grid`, `y-appbar`, `y-sidebar`, `y-tabs`) and controls (`y-checkbox`, `y-radio`, `y-switch`, `y-slider`, `y-progress`). Default rendering is unchanged.
65
73
 
66
- - `y-button` — `--component-button-border-width` is now applied as the `border-width` longhand instead of being baked into the `border` shorthand, so it accepts a 1–4 value pattern for per-side widths (e.g. `0 0 2px 0` for a bottom-only border). Default (`1px`) is unchanged. The `--component-button-outline-border` shorthand override now controls border style + color only; its width is superseded by `--component-button-border-width`.
74
+ - `y-button` — `--component-button-border-width` is now applied as the `border-width` longhand, so it accepts a 1–4 value pattern for per-side widths (e.g. `0 0 2px 0`). The `--component-button-outline-border` override now controls border style and color only.
67
75
 
68
- - Every bordered component now applies its `--component-*-border-width` token as the `border-width` longhand (out of the `border` shorthand), so each accepts a 1–4 value pattern for per-side borders, consistent with `y-button` and the form fields: surfaces/containers (`y-card`, `y-menu`, `y-dialog`, `y-popover`, `y-datepicker`, `y-data-grid`, `y-appbar`, `y-sidebar`, `y-tabs`) and controls (`y-checkbox`, `y-radio`, `y-switch`, `y-slider`, `y-progress`). Default rendering is unchanged.
76
+ - Form fields (`y-input`, `y-textarea`, `y-select`, `y-color`, `y-date`) — `--component-inputs-border-width` is now applied as the `border-width` longhand on every field surface, including the `y-select` dropdown panel and the `y-color` picker popup, so it accepts a 1–4 value pattern for per-side borders.
69
77
 
70
- - Form fields (`y-input`, `y-textarea`, `y-select`, `y-color`, `y-date`) — `--component-inputs-border-width` is now applied as the `border-width` longhand (out of the `border` shorthand) on every field surface, including the `y-select` dropdown panel and the `y-color` picker popup, so like `y-button` it accepts a 1–4 value pattern for per-side borders.
78
+ - `y-button` — new `padding-mode` attribute (`auto` / `square` / `wide`): `auto` makes icon-only buttons square, `square`/`wide` force it. Padding can also be set per-axis via `--component-button-padding-block-{size}` / `--component-button-padding-inline-{size}`. `y-paginator` and `y-datepicker` day/month/year buttons use `padding-mode="square"`.
71
79
 
72
- - `y-button` — Outlined button borders were changed to use semantic border values instead of content color. Padding can now be set per-axis via `--component-button-padding-block-{size}` / `--component-button-padding-inline-{size}` (overriding, and falling back to, the all-sides `--component-button-padding-{size}`), plus a new `padding-mode` attribute (`auto` (default) / `square` / `wide`) controlling whether the inline axis collapses to the block value. `auto` makes icon-only buttons square automatically; `square`/`wide` force it. The Material themes use this for wide pill buttons that stay round when icon-only; `y-paginator` number buttons and `y-datepicker` day / month / year buttons set `padding-mode="square"` so they don't bloat under the wide Material padding.
80
+ - `y-select` — new opt-in `portal` attribute renders the dropdown into the nearest enclosing `<y-theme>` (falling back to `<body>`) so it escapes scrollable or clipped ancestors while keeping the active theme.
73
81
 
74
- - Custom color support expanded to the browser-native color functions — `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, and `color()` — in addition to `#hex`, `rgb()`/`rgba()`, and `hsl()`/`hsla()`. The shared `isSafeCssColor` gate now also tightens its argument allowlist (rejecting semicolons, braces, angle brackets, and nested functions). Applies anywhere a `color` accepts a custom value, including `y-badge`, `y-select`, `y-popover`, `y-button`, `y-tag`, `y-icon`, and `y-rating`.
82
+ - `y-switch` — the "on" state now tints the track and border with the switch color (derived from `on-color`); tint strength is themeable via `--component-switch-on-fill-opacity` (16% default).
75
83
 
76
- - `y-rating` — selected icons now swap in the registered `filled` weight variant instead of just thickening the line stroke, falling back to the thick stroke when no filled variant is available.
84
+ - `y-break` — the divider line now uses the semantic border color (`base.border`), and the host applies default perpendicular spacing via the new `--component-break-spacing` token (defaults to `--spacing-medium`).
77
85
 
78
- - `y-paginator` — page-button list now auto-shrinks to fit the host width, growing back when space allows.
86
+ - `y-checkbox` — the default color themes now mark a checked box with a translucent primary fill, a primary border, and a primary-colored check (via the `--component-checkbox-checked-*` hooks).
79
87
 
80
- - `y-select` — new opt-in `portal` attribute renders the dropdown into `<body>` so it escapes scrollable or clipped ancestors (e.g. inside a data-grid cell editor).
88
+ - `y-radio` — the default color themes now color a selected radio's border with the primary color (via `--component-radio-checked-border-color`). Themes that already define their own checked styling are unchanged.
81
89
 
82
- - **Breaking** `y-break`: `inset` values renamed from `"sm"` / `"md"` / `"lg"` to `"small"` / `"medium"` / `"large"` to match the size scale used by every other component. Spacing mapping is unchanged (`small` → `--spacing-x-small`, `medium` → `--spacing-medium`, `large` → `--spacing-x-large`), so visual output is identical after the find-and-replace.
90
+ - `y-rating` — selected icons now swap in the registered `filled` weight variant, falling back to the thick stroke when none is available.
91
+
92
+ - `y-paginator` — the page-button list now auto-shrinks to fit the host width, growing back when space allows.
83
93
 
84
94
  ### Fixed
85
95
 
86
- - `y-theme` — switching themes now clears the previous theme's CSS custom properties from the host before applying the new ones. Variables defined only by the outgoing theme (e.g. a theme-specific token like `--component-tabs-inactive-background`) previously lingered inline and "stuck" until a page reload; they are now removed on every switch.
96
+ - `y-theme` — theme tokens no longer leak across nested `<y-theme>` boundaries.
97
+
98
+ - `y-theme` — switching themes now clears the previous theme's CSS custom properties from the host, so tokens defined only by the outgoing theme no longer linger inline until reload.
99
+
100
+ - Portaled overlays now inherit the active theme. `y-help`, `y-popover` (`portal` mode), and `y-select` (`portal` mode) rendered into `document.body`, escaping the `<y-theme>` subtree and falling back to the un-themed palette. They now mount into the nearest enclosing `<y-theme>`, walking up across shadow boundaries so it also works inside another component's shadow root, and fall back to `document.body` when there is no theme ancestor.
101
+
102
+ - `y-button` — no longer throws when `color` is set to an unrecognized value; it falls back to the `base` theme instead of crashing while reading the color-token map.
103
+
104
+ - `y-datepicker` — reworked the month and year pickers. The month picker (`show-days="false"`) now shows a selectable year dropdown in its header (toggled by `show-years`) above the twelve months; the year picker (`show-months="false"`) bounds its scrollable grid with start/end year inputs. Clicking a month or year selects it and fires `change`.
105
+
106
+ - `y-droplist` — touch drag now works on iOS Safari and Chrome Android. `touch-action: none` is applied to the press target at decoration time rather than from `pointerdown`, so mobile browsers no longer preempt the press as a scroll.
107
+
108
+ - `y-tabs` — the tab panel no longer creates a stacking context (`z-index: 0` removed), which had trapped `position: fixed` overlays from slotted components beneath the tab strip.
109
+
110
+ - `y-menu` — a menu taller than the viewport now caps its height and scrolls internally. Scrolling engages only on genuine overflow, so normal menus keep their CSS flyout submenus.
111
+
112
+ - `y-menu` — a menu anchored to a disabled trigger no longer opens on click. The anchor's disabled state (native `disabled`, reflected `disabled`, or `aria-disabled="true"`) is checked at click time.
87
113
 
88
- - `y-tabs` — unselected tabs now use a dedicated `--component-tabs-inactive-background` (falling back to `--component-tabs-border-color`, so existing themes are unchanged) instead of always painting the tab background with the border color. This fixes the Neobrutalist themes, where the border color equals the text color and made unselected tab labels unreadable; both Neobrutalist themes now set it to a distinct surface tone.
114
+ - `y-menu` — selected items now use the primary-inverse content color, keeping labels readable against the selected background across themes.
89
115
 
90
- - Portaled overlays now inherit the active theme. `y-help` (tour overlay/tooltip), `y-popover` (`portal` mode), and `y-select` (`portal` mode) previously rendered into `document.body`, escaping the `<y-theme>` subtree that scopes the theme's CSS custom properties — so they fell back to the default un-themed palette. They now mount into the nearest enclosing `<y-theme>` (falling back to `document.body` when there isn't one), so the portaled surface matches the active theme and tracks live theme switches. Keep the component inside your `<y-theme>`.
116
+ - `y-sidebar` — nav/footer icons now stay aligned between expanded and collapsed states under themes whose borders use a multi-value width. The icon-column width is derived from the sidebar's resolved horizontal border instead of a `calc()` that mishandled the multi-value token.
91
117
 
92
- - Form field components now share one field background. `y-select` (trigger and dropdown) used `base.background.app` while `y-input` / `y-textarea` / `y-color` / `y-date` used `base.background.component`; `select.background` is now `base.background.component` across all themes, so fields match when placed together on a form (most visible in the Material and Carbon themes). The select dropdown panel now also matches menus/popovers.
118
+ - `y-appbar` — a stickied appbar now renders its content-facing border correctly under themes with per-side border widths. The sticky styles now use the `border-width` shorthand and zero only the screen-flush edges.
93
119
 
94
- - `y-avatar` — the three `shape` values are now visually distinct. Added a `--component-avatar-border-radius-rounded` token (medium radius) and changed `square` to a zero radius (sharp corners); `circle` is unchanged.
120
+ - `y-tabs` — unselected tabs now use a dedicated `--component-tabs-inactive-background` (falling back to `--component-tabs-border-color`), fixing unreadable labels in themes where the border and text colors match.
95
121
 
96
- - `y-tag` — Increased the inline padding size for all sizes of `y-tag` component.
122
+ - Form fields now share one background (`base.background.component`), so a `y-select` matches sibling `y-input` / `y-textarea` / `y-color` / `y-date` fields and the select dropdown matches menus/popovers.
97
123
 
98
- - `y-tabs` — the tab panel no longer creates a stacking context (`z-index: 0` removed), which was trapping `position: fixed` overlays rendered by slotted components (e.g. `y-gallery`'s lightbox) underneath the tab strip and surrounding page content.
124
+ - `y-gallery` — the lightbox z-index was raised from 1000 to 9000 so it layers above fixed chrome like `y-dock`; override via `--component-gallery-expand-z-index`.
99
125
 
100
- - `y-gallery` — the lightbox overlay's default z-index was raised from 1000 to 9000 so it layers above fixed chrome like `y-dock` (8000); override via `--component-gallery-expand-z-index`.
126
+ - React JSX types (`react.d.ts`) and the bundled AI docs (`llm.txt`, skill reference) were brought back in sync, adding missing attribute types and correcting several defaults. A new `npm run check:docs` gate cross-checks observed attributes against all three docs in `pretest` / `prepublishOnly`.
101
127
 
102
- - `y-menu` — selected items now use the primary inverse content color for their text, so the label stays readable against the primary-colored selected background across all themes.
128
+ - `y-drawer` — corners closest to the screen edge are now squared in all themes.
103
129
 
104
- - `y-button` — no longer throws when `color` is set to an unrecognized value that isn't a valid custom color; it now falls back to the `base` theme instead of crashing while reading the color-token map.
130
+ - `y-avatar` — the three `shape` values are now visually distinct: added `--component-avatar-border-radius-rounded` (medium radius) and changed `square` to a zero radius; `circle` is unchanged.
105
131
 
106
- - `y-droplist` — touch drag now works reliably on iOS Safari and Chrome Android. `touch-action: none` is applied to the press target at decoration time instead of from inside `pointerdown`, so mobile browsers stop preempting the press as a scroll gesture.
132
+ - Corrected the arrow direction on the `left-from-bracket`, `right-from-bracket`, and `left-to-bracket` icons: `*-from-*` arrows now exit the bracket and `*-to-*` enters it.
107
133
 
108
- - Corrected the arrow direction on the `left-from-bracket`, `right-from-bracket`, and `left-to-bracket` icons, which previously pointed the wrong way relative to their bracket (the `*-from-*` arrows now exit the bracket and the `*-to-*` arrow enters it).
134
+ - `y-tag` — increased inline padding across all sizes.
109
135
 
110
136
  ## [0.5.0] - 2026-05-25
111
137
 
package/CONTRIBUTING.md CHANGED
@@ -34,7 +34,7 @@ Yumekit is authored in plain JavaScript. Please follow the conventions already p
34
34
  - Components are standard Custom Elements with no external framework dependencies.
35
35
  - Use `kebab-case` for element names and attribute names.
36
36
  - Keep components self-contained: styles live in the Shadow DOM, logic in the class, no shared global state.
37
- - Run the linter before submitting: `npm run lint`.
37
+ - Run the linter before submitting: `npx eslint .` (configured in `eslint.config.mjs`).
38
38
 
39
39
  ## Component Authoring Guidelines
40
40
 
@@ -93,12 +93,14 @@ The DOM-element, icon, and slot rules above exist primarily to keep user-control
93
93
 
94
94
  ### New component checklist
95
95
 
96
- Every new component requires changes to the following: `README.md`, `CHANGELOG.md`, `reference.md`, `SKILL.md`, `react.d.ts`, its token sets under `tokens/` (see [Design Tokens](#design-tokens)), entry in `llm.txt`, and a `y-*.stories.js` stories file.
96
+ Every new component requires changes to the following: `README.md`, `CHANGELOG.md`, `reference.md`, `SKILL.md`, `react.d.ts`, its token sets under `tokens/` (see [Design Tokens](#design-tokens)), entry in `llm.txt`, and a `y-*.stories.js` stories file. See [AI Documentation](#ai-documentation) for the docs that are checked automatically.
97
97
 
98
98
  ### Testing
99
99
 
100
100
  - Tests co-locate with the component source file.
101
- - Use `sinon.createSandbox()` at the `describe` level with `afterEach(() => sandbox.restore())`.
101
+ - Use `sinon.createSandbox()` at the `describe` level with `afterEach(() => sandbox.restore())`. Never call `stub.restore()` manually — it leaks on assertion failure.
102
+ - Use `sandbox.stub(...)` rather than `sinon.stub(...)` directly.
103
+ - Run the suite with `npm test` (Web Test Runner with coverage).
102
104
 
103
105
  ## Design Tokens
104
106
 
@@ -126,6 +128,17 @@ Generated outputs:
126
128
 
127
129
  Use the [Tokens Studio for Figma](https://tokens.studio/) plugin pointed at this repo's `tokens/` directory to keep Figma Variables in sync with code.
128
130
 
131
+ ## AI Documentation
132
+
133
+ Yumekit ships AI-facing docs alongside the package: `llm.txt` and the Claude skill under `.claude/skills/yumekit/` (`SKILL.md`, `reference.md`, `patterns.md`, `examples/`). These are bundled into `dist/ai/` at build time and can be installed into a consumer project with `npx @waggylabs/yumekit init-ai`.
134
+
135
+ Two scripts keep these docs honest, and both run automatically in `pretest` and `prepublishOnly`:
136
+
137
+ - **`npm run sync:docs`** stamps mechanical numbers (package version, registered-component count, theme count) into `llm.txt` and the skill docs from source. Don't hand-edit those numbers. Run with `-- --check` to fail on drift.
138
+ - **`npm run check:docs`** cross-references each component's `observedAttributes` against `react.d.ts`, `llm.txt`, and `reference.md`, flagging any observed attribute that isn't documented. It checks attribute *names* only — value enums, defaults, and prose are still up to you.
139
+
140
+ When you add or change a component's public API (attributes, slots, events, methods), update its entry in `llm.txt`, `.claude/skills/yumekit/reference.md`, and the JSX types in `src/react.d.ts` in the same change. The sync script does not author this prose for you.
141
+
129
142
  ## AI Assistance
130
143
 
131
144
  AI tools can be helpful for brainstorming and prototyping, but they are not a substitute for human judgment and expertise.
package/README.md CHANGED
@@ -17,7 +17,7 @@
17
17
 
18
18
  ## Overview
19
19
 
20
- YumeKit is a collection of 41 production-ready custom elements built with native Web Components. It works with any framework — or none at all — and ships with a comprehensive design token system, built-in theming, an icon registry, and full TypeScript support.
20
+ YumeKit is a collection of 51 production-ready components built with native Web Components. It works with any framework — or none at all — and ships with a comprehensive design token system, built-in theming, an icon registry, and full TypeScript support.
21
21
 
22
22
  - **Zero dependencies** — built entirely on web standards
23
23
  - **Framework-agnostic** — works with React, Vue, Svelte, or plain HTML
@@ -73,47 +73,68 @@ Then use the `<y-theme>` component to apply a theme:
73
73
 
74
74
  ## Components
75
75
 
76
- | Component | Element | Description |
77
- | ------------ | ------------------ | --------------------------------------------------- |
78
- | App Bar | `<y-appbar>` | Top or side navigation bar |
79
- | Avatar | `<y-avatar>` | User avatar with shape and color variants |
80
- | Badge | `<y-badge>` | Status badge or label |
81
- | Break | `<y-break>` | Divider with optional centered label, icon, or slot |
82
- | Breadcrumbs | `<y-breadcrumbs>` | Navigation breadcrumb trail with collapse support |
83
- | Button | `<y-button>` | Button with icon, size, and style variants |
84
- | Button Group | `<y-button-group>` | Groups buttons (or inputs) into a connected toolbar |
85
- | Card | `<y-card>` | Content card container |
86
- | Checkbox | `<y-checkbox>` | Form checkbox input |
87
- | Date | `<y-date>` | Date input |
88
- | DatePicker | `<y-datepicker>` | A date and time picker |
89
- | Dialog | `<y-dialog>` | Modal dialog |
90
- | Dock | `<y-dock>` | Fixed navigation dock |
91
- | Drawer | `<y-drawer>` | Side drawer / sidebar |
92
- | Droplist | `<y-droplist>` | Drag-and-drop reorderable list |
93
- | Gallery | `<y-gallery>` | Media gallery with lightbox |
94
- | Grid | `<y-grid>` | CSS Grid layout container |
95
- | Icon | `<y-icon>` | SVG icon display |
96
- | Input | `<y-input>` | Text input field |
97
- | Masonry | `<y-masonry>` | JS-positioned masonry layout |
98
- | Menu | `<y-menu>` | Dropdown navigation menu |
99
- | Panel | `<y-panel>` | Accordion panel |
100
- | Panel Bar | `<y-panelbar>` | Accordion panel group |
101
- | Progress | `<y-progress>` | Progress bar |
102
- | Radio | `<y-radio>` | Radio button input |
103
- | Rating | `<y-rating>` | Star / icon rating input |
104
- | Select | `<y-select>` | Select / dropdown input |
105
- | Slider | `<y-slider>` | Range slider input |
106
- | Splitter | `<y-splitter>` | Two-pane container with a draggable resize handle |
107
- | Stack | `<y-stack>` | Flexbox layout container (row or column) |
108
- | Stepper | `<y-stepper>` | Multi-step wizard with sequential flow |
109
- | Switch | `<y-switch>` | Toggle switch |
110
- | Table | `<y-table>` | Sortable data table |
111
- | Textarea | `<y-textarea>` | Multi-line text input |
112
- | Tabs | `<y-tabs>` | Tabbed interface |
113
- | Tag | `<y-tag>` | Tag / chip label |
114
- | Theme | `<y-theme>` | Theme provider |
115
- | Toast | `<y-toast>` | Notification toast |
116
- | Tooltip | `<y-tooltip>` | Tooltip / popover |
76
+ | Component | Element | Description |
77
+ | ------------- | ------------------ | ------------------------------------------------------- |
78
+ | Animate | `<y-animate>` | Scroll/viewport-triggered animation wrapper |
79
+ | App Bar | `<y-appbar>` | Top or side navigation bar |
80
+ | Avatar | `<y-avatar>` | User avatar with shape and color variants |
81
+ | Avatar Group | `<y-avatar-group>` | Overlapping avatar group with overflow count |
82
+ | Badge | `<y-badge>` | Status badge or label |
83
+ | Banner | `<y-banner>` | Full-width inline message / alert banner |
84
+ | Break | `<y-break>` | Divider with optional centered label, icon, or slot |
85
+ | Breadcrumbs | `<y-breadcrumbs>` | Navigation breadcrumb trail with collapse support |
86
+ | Button | `<y-button>` | Button with icon, size, and style variants |
87
+ | Button Group | `<y-button-group>` | Groups buttons (or inputs) into a connected toolbar |
88
+ | Card | `<y-card>` | Content card container |
89
+ | Checkbox | `<y-checkbox>` | Form checkbox input |
90
+ | Code | `<y-code>` | Code block with built-in syntax highlighting |
91
+ | Color | `<y-color>` | Color swatch / value display |
92
+ | Color Picker | `<y-colorpicker>` | Interactive color picker |
93
+ | Data Grid | `<y-data-grid>` | Data grid with sorting, filtering, editing, pagination |
94
+ | Date | `<y-date>` | Date input |
95
+ | DatePicker | `<y-datepicker>` | A date and time picker |
96
+ | Dialog | `<y-dialog>` | Modal dialog |
97
+ | Dock | `<y-dock>` | Fixed navigation dock |
98
+ | Drawer | `<y-drawer>` | Side drawer / sidebar |
99
+ | Droplist | `<y-droplist>` | Drag-and-drop reorderable list |
100
+ | Gallery | `<y-gallery>` | Media gallery with lightbox |
101
+ | Grid | `<y-grid>` | CSS Grid layout container |
102
+ | Help | `<y-help>` | Guided product tour / onboarding walkthrough |
103
+ | Icon | `<y-icon>` | SVG icon display |
104
+ | Input | `<y-input>` | Text input field |
105
+ | Masonry | `<y-masonry>` | JS-positioned masonry layout |
106
+ | Menu | `<y-menu>` | Dropdown navigation menu |
107
+ | Paginator | `<y-paginator>` | Pagination controls |
108
+ | Panel Bar | `<y-panelbar>` | Accordion panel group |
109
+ | Popover | `<y-popover>` | Anchored floating popover |
110
+ | Progress | `<y-progress>` | Progress bar |
111
+ | Radio | `<y-radio>` | Radio button input |
112
+ | Rating | `<y-rating>` | Star / icon rating input |
113
+ | Select | `<y-select>` | Select / dropdown input |
114
+ | Shape | `<y-shape>` | Decorative CSS shape container |
115
+ | Sidebar | `<y-sidebar>` | Collapsible app sidebar navigation |
116
+ | Slider | `<y-slider>` | Range slider input |
117
+ | Splitter | `<y-splitter>` | Two-pane container with a draggable resize handle |
118
+ | Stack | `<y-stack>` | Flexbox layout container (row or column) |
119
+ | Stepper | `<y-stepper>` | Multi-step wizard with sequential flow |
120
+ | Switch | `<y-switch>` | Toggle switch |
121
+ | Table | `<y-table>` | Sortable data table |
122
+ | Tabs | `<y-tabs>` | Tabbed interface |
123
+ | Tag | `<y-tag>` | Tag / chip label |
124
+ | Textarea | `<y-textarea>` | Multi-line text input |
125
+ | Theme | `<y-theme>` | Theme provider |
126
+ | Toast | `<y-toast>` | Notification toast |
127
+ | Tooltip | `<y-tooltip>` | Tooltip / popover |
128
+ | Tree | `<y-tree>` | Hierarchical tree view |
129
+
130
+ ### Sub-elements
131
+
132
+ These are building blocks used inside their parent component, not standalone components (and not included in the count above):
133
+
134
+ | Element | Used inside | Description |
135
+ | --------------- | -------------- | -------------------------------- |
136
+ | `<y-panel>` | `<y-panelbar>` | Individual accordion panel |
137
+ | `<y-tree-item>` | `<y-tree>` | Individual node within a tree |
117
138
 
118
139
  ---
119
140