@waggylabs/yumekit 0.4.3-beta.39 → 0.4.3-beta.41

package/CHANGELOG.md

@@ -36,11 +36,18 @@ Delete any empty sections before publishing.
 ### Added
 
 - New `y-stepper` component — a multi-step wizard that guides users through a sequential flow. Step content is provided via named slots defined in the `items` JSON array (`{ label, slot, description?, icon?, status? }`). Supports `current` (zero-based active step index), `orientation` (`"horizontal"` | `"vertical"`), `position` (`"start"` | `"end"` — controls whether indicators appear before or after the content), `size` (`"small"` | `"medium"` | `"large"`), `linear` (restricts free navigation), and `editable` (allows returning to completed steps). Methods: `next()`, `previous()`, `goTo(index)`, `complete(index?)`, `reset()`. Events: cancelable `change`, `complete`, `finish`. Full ARIA support with `role="list"`, `aria-current="step"`, `aria-controls`/`aria-labelledby` linkage, and keyboard navigation.
+- New `y-breadcrumbs` component — a navigation breadcrumb trail. Accepts an `items` JSON array (`{ text, href?, icon? }`). Supports `separator` (custom separator character or slotted icon), `max-items` (collapses middle items with an expand button), `size` (`"small"` | `"medium"` | `"large"`), and `history` (set to `"false"` for full-page navigation instead of `pushState`). Fires cancelable `navigate` and `expand` events. Full ARIA with `<nav aria-label="Breadcrumb">`, `<ol>`, `aria-current="page"`, and `aria-hidden` separators.
 - New `y-gallery` component — a media gallery that accepts `<img>` or `<figure>` children and arranges them in `grid`, `row`, `column`, or `masonry` layouts. Supports `columns`, `gap` (`"small"` | `"medium"` | `"large"` or any CSS length), `aspect-ratio`, `expandable` (lightbox with prev/next navigation), `loop`, and `size` attributes. The expanded view uses `<y-icon>` for nav arrows and supports `data-src` for full-resolution images, `<figcaption>` captions, and image counter. Icon slots (`expand-prev-icon`, `expand-next-icon`, `expand-close-icon`) allow custom icons. Fires `expand`, `close`, and `navigate` events.
 - New `y-colorpicker` component — a standalone color picker widget with a 2D saturation/brightness canvas, hue slider, optional alpha slider, format selector, and channel inputs. Supports `value` (`#hex`, `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hsv()`, `hsva()`), `format` (`"hex"` | `"rgb"` | `"hsl"` | `"hsv"`), `formats` (JSON array of available formats), `show-alpha` (alpha channel), and `size` attributes.
 - New `y-color` component — a form-associated color input with a trigger/popup pattern (like `<y-date>`). Renders a color swatch preview and value string in the trigger; opens a `<y-colorpicker>` popup on click. Supports `value`, `format`, `formats`, `show-alpha`, `placeholder`, `name`, `disabled`, `invalid`, `clearable`, `size`, and `label-position` attributes. Uses `ElementInternals` for `FormData` participation.
 - New `y-banner` component — a full-width informational banner that renders in a semantic color with matching text. Supports `color` (`"base"` | `"primary"` | `"secondary"` | `"success"` | `"error"` | `"warning"` | `"help"`), `icon` attribute (or `icon` slot), `position` (`"push"` | `"overlap"`), `sticky` (fixed to viewport when overlapping), `dismissable` close button, `size` (`"small"` | `"medium"` | `"large"`), and an `action` slot for CTA elements.
 - New `y-stack` component — a layout container for arranging child elements in rows, columns, grids, or masonry patterns. Supports `mode` (`"flex"` | `"grid"` | `"masonry"`), `direction`, `columns`, `gap` (maps to `--spacing-*` tokens), `wrap`, `align`, `justify`, and `responsive` attributes. Masonry mode uses JS absolute positioning with `ResizeObserver`. Responsive mode auto-collapses columns at configurable breakpoints.
+- `y-tabs`: `leftIcon` and `rightIcon` properties on option objects — set a `<y-icon>` name directly in the options JSON to render icons without requiring extra child elements or named slots.
+- `y-tabs`: `tab-content-{id}` slot — place any content (icons, badges, custom markup) inside the tab button itself by targeting this slot. Takes full precedence over `leftIcon`/`rightIcon` and the default label rendering.
+
+### Deprecated
+
+- `y-tabs`: `left-icon-{id}` and `right-icon-{id}` slots — these slots still function but emit a `console.warn` directing users to the `leftIcon`/`rightIcon` option properties or the `tab-content-{id}` slot. They will be removed before the release of version 1.0.
 
 ## [0.4.2] - 2026-04-07
 

package/CONTRIBUTING.md

@@ -36,6 +36,62 @@ Yumekit is authored in plain JavaScript. Please follow the conventions already p
 - Keep components self-contained: styles live in the Shadow DOM, logic in the class, no shared global state.
 - Run the linter before submitting: `npm run lint`.
 
+## Component Authoring Guidelines
+
+### Class structure
+
+Every component class must have exactly four comment-delimited sections in this order — no more, no subdivisions:
+
+```
+// Lifecycle
+// Getters / Setters
+// Public
+// Private
+```
+
+Methods within their subdivision must be listed alphabetically.
+
+### Method style
+
+Follow a **define → compute → return/apply** flow within each method where possible: gather inputs and state at the top, do the work in the middle, produce output at the end. Keep methods small and focused — if a method grows long or does multiple distinct things, extract a named helper. Minimize nesting by preferring early returns over deep `if/else` trees. Separate distinct logical units of work with blank lines. This ruleset allows humans and AI to have a predictable and human-readable code structure upon which to base future updates.
+
+### DOM element creation
+
+Use the `createElement` helper (imported as `_el`) from `src/modules/helpers.js` for all element creation inside components. Do not use manual `document.createElement` + `setAttribute` chains.
+
+```js
+import { createElement as _el } from "../../modules/helpers.js";
+
+const btn = _el("button", { role: "tab", "aria-label": label }, [labelText]);
+```
+
+### Icons
+
+Use `<y-icon name="...">` for all icons. Never inline SVG strings or constants. Import `y-icon.js` at the top of any component that renders icons.
+
+### Slot patterns
+
+Always render named slots unconditionally and place default/fallback content as **children of the slot element**. Never use `querySelector` to decide whether to create a slot. This breaks framework rendering (React, Vue, etc.) where children may arrive after the element upgrades.
+
+```js
+// Correct
+const slot = _el("slot", { name: "icon" });
+slot.appendChild(defaultIcon);
+parent.appendChild(slot);
+
+// Wrong — slot is conditional on a render-time DOM query
+if (this.querySelector('[slot="icon"]')) { ... }
+```
+
+### New component checklist
+
+Every new component requireschanges to the following: `README.md`, `CHANGELOG.md`, `reference.md`, `SKILL.md`, `react.d.ts`, `variables.css`, `.figma/variables.json`, entry in `llm.txt`, and a `y-*.stories.js` stories file.
+
+### Testing
+
+- Tests co-locate with the component source file.
+- Use `sinon.createSandbox()` at the `describe` level with `afterEach(() => sandbox.restore())`.
+
 ## AI Assistance
 
 AI tools can be helpful for brainstorming and prototyping, but they are not a substitute for human judgment and expertise.

package/README.md

@@ -17,7 +17,7 @@
 
 ## Overview
 
-YumeKit is a collection of 33 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.
+YumeKit is a collection of 34 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.
 
 - **Zero dependencies** — built entirely on web standards
 - **Framework-agnostic** — works with React, Vue, Svelte, or plain HTML
@@ -78,6 +78,7 @@ Then use the `<y-theme>` component to apply a theme:
 | App Bar      | `<y-appbar>`       | Top or side navigation bar                          |
 | Avatar       | `<y-avatar>`       | User avatar with shape and color variants           |
 | Badge        | `<y-badge>`        | Status badge or label                               |
+| Breadcrumbs  | `<y-breadcrumbs>`  | Navigation breadcrumb trail with collapse support   |
 | Button       | `<y-button>`       | Button with icon, size, and style variants          |
 | Button Group | `<y-button-group>` | Groups buttons (or inputs) into a connected toolbar |
 | Card         | `<y-card>`         | Content card container                              |

package/dist/components/y-breadcrumbs/y-breadcrumbs.d.ts

@@ -0,0 +1,35 @@
+export class YumeBreadcrumbs extends HTMLElement {
+    static get observedAttributes(): string[];
+    _expanded: boolean;
+    connectedCallback(): void;
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+    set history(val: string);
+    /** When omitted, navigation uses pushState. Set to "false" for full-page navigation. */
+    get history(): string;
+    set items(val: any);
+    /** Array of breadcrumb items. */
+    get items(): any;
+    set maxItems(val: number);
+    /** Maximum visible items before collapsing. */
+    get maxItems(): number;
+    set separator(val: string);
+    /** Text or character used as the separator. Defaults to a chevron-right icon when unset. */
+    get separator(): string;
+    set size(val: string);
+    /** Controls padding, font size, and icon size. */
+    get size(): string;
+    render(): void;
+    _buildExpandItem(): HTMLElement;
+    _buildHostStyles(): string;
+    _buildItem(item: any, index: any, items: any): HTMLElement;
+    _buildItemStyles(): string;
+    _buildSeparatorItem(): HTMLElement;
+    _buildSeparatorStyles(): string;
+    _buildStyles(): string;
+    _getDefaultFontSize(): any;
+    _getDefaultGap(): any;
+    _getIconSize(): any;
+    _getVisibleItems(items: any): any;
+    _onExpand(): void;
+    _onNavigate(e: any, href: any): void;
+}

package/dist/components/y-breadcrumbs.d.ts

@@ -0,0 +1,35 @@
+export class YumeBreadcrumbs extends HTMLElement {
+    static get observedAttributes(): string[];
+    _expanded: boolean;
+    connectedCallback(): void;
+    attributeChangedCallback(name: any, oldValue: any, newValue: any): void;
+    set history(val: string);
+    /** When omitted, navigation uses pushState. Set to "false" for full-page navigation. */
+    get history(): string;
+    set items(val: any);
+    /** Array of breadcrumb items. */
+    get items(): any;
+    set maxItems(val: number);
+    /** Maximum visible items before collapsing. */
+    get maxItems(): number;
+    set separator(val: string);
+    /** Text or character used as the separator. Defaults to a chevron-right icon when unset. */
+    get separator(): string;
+    set size(val: string);
+    /** Controls padding, font size, and icon size. */
+    get size(): string;
+    render(): void;
+    _buildExpandItem(): HTMLElement;
+    _buildHostStyles(): string;
+    _buildItem(item: any, index: any, items: any): HTMLElement;
+    _buildItemStyles(): string;
+    _buildSeparatorItem(): HTMLElement;
+    _buildSeparatorStyles(): string;
+    _buildStyles(): string;
+    _getDefaultFontSize(): any;
+    _getDefaultGap(): any;
+    _getIconSize(): any;
+    _getVisibleItems(items: any): any;
+    _onExpand(): void;
+    _onNavigate(e: any, href: any): void;
+}