@ziyarago/ui 0.0.0-stage → 0.1.0

package/src/core/dialog.js

@@ -0,0 +1,65 @@
+// Shared dialog behaviour: Escape, focus move/trap/restore. Used as a function ref on the dialog element, so
+// it runs only in a browser (SSR ignores refs) and listeners exist only while a dialog is mounted.
+const reg = new WeakMap(), stack = [], pend = new WeakMap();
+// Adapters may call a ref before the element is attached (Transition, detached parents): wait until it is in the document.
+const whenConnected = (el, opts, run) => {
+  if (el.isConnected) return run(el, opts);
+  const w = pend.get(el); if (w) { w.opts = opts; return; }
+  const q = { opts }; pend.set(el, q);
+  const step = n => { if (el.isConnected) { pend.delete(el); run(el, q.opts); } else if (n < 60) requestAnimationFrame(() => step(n + 1)); else pend.delete(el); };
+  queueMicrotask(() => step(0));
+};
+const SEL = 'a[href],button:not([disabled]),input:not([disabled]):not([type=hidden]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"]),[contenteditable="true"]';
+const focusables = el => [...el.querySelectorAll(SEL)].filter(n => n.tabIndex >= 0 && n.getClientRects().length > 0 && !n.closest('[inert]'));
+const onKey = e => {
+  const r = stack[stack.length - 1]; if (!r) return;
+  const o = r.opts;
+  if (o.onKey && o.onKey(e) === true) return;
+  if (e.key === 'Escape' && !e.defaultPrevented && o.onClose) { e.preventDefault(); o.onClose(e); return; }
+  if (e.key !== 'Tab' || o.focus === false) return;
+  const list = focusables(r.el), a = document.activeElement;
+  if (!list.length) { e.preventDefault(); r.el.focus(); return; }
+  const first = list[0], last = list[list.length - 1], inside = r.el.contains(a) && a !== r.el;
+  if (e.shiftKey && (!inside || a === first)) { e.preventDefault(); last.focus(); }
+  else if (!e.shiftKey && (!inside || a === last)) { e.preventDefault(); first.focus(); }
+};
+const mount = (el, opts) => {
+  let prev = document.activeElement;
+  for (const o of [...stack]) if (!o.el.isConnected) { if ((!prev || prev === document.body) && o.prev) prev = o.prev; drop(o, true); }
+  const r = { el, opts, prev };
+  reg.set(el, r);
+  if (opts.mount) r.cleanup = opts.mount(el, () => r.opts);
+  if (!stack.length) document.addEventListener('keydown', onKey);
+  stack.push(r);
+  if (opts.focus !== false) {
+    if (!el.hasAttribute('tabindex')) el.setAttribute('tabindex', '-1');
+    (el.querySelector('[data-autofocus],[autofocus]') || focusables(el)[0] || el).focus({ preventScroll: true });
+  }
+};
+const drop = (r, silent) => {
+  const i = stack.indexOf(r); if (i >= 0) stack.splice(i, 1);
+  reg.delete(r.el);
+  if (r.cleanup) r.cleanup();
+  if (!stack.length) document.removeEventListener('keydown', onKey);
+  const p = r.prev;
+  const a = document.activeElement;
+  if (!silent && r.opts.focus !== false && p && p.isConnected && typeof p.focus === 'function' && (!a || a === document.body || r.el.contains(a))) p.focus({ preventScroll: true });
+};
+const sweep = () => { for (const r of [...stack]) if (!r.el.isConnected) drop(r); };
+// opts: { mount(el, getOpts) -> cleanup fn (runs once per open), onClose, onKey(e) (return true to skip default handling), focus: false to disable focus handling }
+export const trap = (opts = {}) => el => {
+  if (typeof document === 'undefined') return;
+  if (!el) return queueMicrotask(sweep);
+  const r = reg.get(el);
+  if (r) r.opts = opts; else whenConnected(el, opts, mount);
+};
+
+// Lifecycle-only ref (no keys/focus): mount(el, getOpts) runs once when the element appears and returns a cleanup run when it goes away.
+const lreg = new Map();
+const lsweep = () => { for (const [el, r] of [...lreg]) if (!el.isConnected) { lreg.delete(el); if (r.cleanup) r.cleanup(); } };
+export const life = opts => el => {
+  if (typeof document === 'undefined') return;
+  if (!el) return queueMicrotask(lsweep);
+  const r = lreg.get(el);
+  if (r) r.opts = opts; else whenConnected(el, opts, (e, o) => { const n = { opts: o }; lreg.set(e, n); if (o.mount) n.cleanup = o.mount(e, () => n.opts); });
+};

package/src/core/index.js

@@ -0,0 +1,9 @@
+import { components as base, fmt, setIconBase } from './components.js';
+import { more } from './components2.js';
+import { more3 } from './components3.js';
+import { more4, rules } from './components4.js';
+import { pages } from './pages.js';
+import { more6 } from './components6.js';
+import { more7 } from './components7.js';
+export const components = { ...base, ...more, ...more3, ...more4, ...more6, ...more7, ...pages };
+export { fmt, setIconBase, rules };

package/src/core/pages.js

@@ -0,0 +1,51 @@
+// @ziyarago/ui · page templates — real slot contracts. Put inside <UiAppShell>, fill only the slots you need.
+// Vue:   <UiPageDashboard title="Dashboard"><template #kpis>…</template></UiPageDashboard>
+// React: <UiPageDashboard title="Dashboard" kpis={<…/>} />
+import { cx } from './components.js';
+
+const region = (h, id, kids) => (kids == null || (Array.isArray(kids) && !kids.length)) ? null : h('div', { key: id, class: 'zg-pg__r', 'data-slot': id }, kids);
+
+const draw = (h, node, ctx) => {
+  if (typeof node === 'string') return node === 'header' ? ctx.header() : region(h, node, ctx.slots[node]);
+  const [kind, ...a] = node, go = n => draw(h, n, ctx);
+  if (kind === 'col') return h('div', { class: 'zg-pg' }, ...a.map(go));
+  if (kind === 'auto') { const min = a.shift(); return h('div', { class: 'zg-pg__auto', style: { '--min': min + 'px' } }, ...a.map(go)); }
+  if (kind === 'two') return h('div', { class: 'zg-pg__two' }, h('div', { class: 'zg-pg__main' }, ...a[0].map(go)), h('div', { class: 'zg-pg__side' }, ...a[1].map(go)));
+  if (kind === 'wrap') return h('div', { class: 'zg-pg__two' }, h('div', { class: 'zg-pg__aside', style: { flexBasis: (a[2] || 300) + 'px' } }, ...a[0].map(go)), h('div', { class: 'zg-pg__main' }, ...a[1].map(go)));
+  return null;
+};
+
+const page = (name, slots, tree) => [name, {
+  slots,
+  render: ({ C, h, props: p, slots: s }) => {
+    const header = () => s.header ? region(h, 'header', s.header) : (p.title ? h('div', { class: 'zg-pg__r', 'data-slot': 'header' }, h('div', { class: 'zg-page-head' }, h('div', { style: { flex: 1, minWidth: 0 } }, p.crumbs ? h(C.Breadcrumbs, { items: p.crumbs }) : null, h('h1', null, p.title), p.subtitle ? h('p', null, p.subtitle) : null), s.actions || null)) : (s.actions ? h('div', { class: 'zg-pg__r', 'data-slot': 'header' }, h('div', { class: 'zg-page-head', style: { justifyContent: 'flex-end' } }, s.actions)) : null));
+    return h('div', { class: 'zg-pgroot' }, draw(h, tree, { slots: s, header }));
+  }
+}];
+
+const T = Object.fromEntries([
+  page('PageDashboard', ['header', 'hero', 'kpis', 'occupancy', 'funnel', 'top', 'activity'], ['col', 'header', ['auto', 340, 'hero', 'kpis'], ['auto', 360, 'occupancy', 'funnel'], ['auto', 360, 'top', 'activity']]),
+  page('PagePatterns', ['header', 'hero', 'strip', 'statlines', 'chartcard', 'tiles', 'listrows', 'countries', 'versus', 'segbar', 'activity', 'actioncard'], ['col', 'header', ['auto', 340, 'hero', 'strip'], 'statlines', ['auto', 360, 'chartcard', 'tiles'], ['auto', 320, 'listrows', 'countries', 'versus'], 'segbar', ['auto', 360, 'activity', 'actioncard']]),
+  page('PageCrm', ['header', 'summary', 'filters', 'board', 'calls'], ['col', 'header', 'summary', 'filters', 'board', 'calls']),
+  page('PageBookings', ['header', 'stats', 'toolbar', 'bulk', 'table', 'pager'], ['col', 'header', 'stats', 'toolbar', 'bulk', 'table', 'pager']),
+  page('PageCatalog', ['header', 'filters', 'toolbar', 'grid', 'pager'], ['col', 'header', ['wrap', ['filters'], ['toolbar', 'grid', 'pager'], 260]]),
+  page('PageDetail', ['header', 'gallery', 'summary', 'tabs', 'history', 'booking'], ['col', 'header', ['two', ['gallery', 'summary', 'tabs', 'history'], ['booking']]]),
+  page('PageSettings', ['header', 'subnav', 'profile', 'notifications', 'integrations', 'danger'], ['col', 'header', ['wrap', ['subnav'], ['profile', 'notifications', 'integrations', 'danger'], 220]]),
+  page('PageUserList', ['header', 'stats', 'filters', 'toolbar', 'table', 'drawer'], ['col', 'header', 'stats', ['two', ['filters', 'toolbar', 'table'], ['drawer']]]),
+  page('PageProfile', ['header', 'profile', 'tabs', 'about', 'activity', 'plan'], ['col', 'header', 'profile', 'tabs', ['wrap', ['about'], ['activity', 'plan'], 320]]),
+  page('PageForm', ['header', 'main', 'media', 'side', 'actions'], ['col', 'header', ['two', ['main', 'media'], ['side']]]),
+  page('PageOrder', ['header', 'status', 'items', 'shipping', 'side'], ['col', 'header', 'status', ['two', ['items', 'shipping'], ['side']]]),
+  page('PageAccount', ['header', 'tabs', 'panel'], ['col', 'header', 'tabs', 'panel']),
+  page('PagePricing', ['header', 'toggle', 'plans', 'faq'], ['col', 'header', 'toggle', 'plans', 'faq']),
+  page('PageFaq', ['header', 'search', 'cats', 'answers', 'contact'], ['col', 'header', 'search', ['wrap', ['cats'], ['answers'], 200], 'contact'])
+]);
+
+T.PageAuth = { slots: ['background', 'logo', 'aside', 'form', 'footer'], render: ({ C, h, props: p, slots: s }) => {
+  const body = [s.form || null, s.footer ? h('div', { class: 'zg-pg__r', 'data-slot': 'footer' }, s.footer) : null];
+  return p.layout === 'split'
+    ? h(C.AuthSplit, { title: p.title, subtitle: p.subtitle, logo: s.logo, aside: s.aside }, ...body)
+    : h('div', { class: 'zg-pgauth' }, s.background ? h('div', { class: 'zg-pg__r zg-pgauth__bg', 'data-slot': 'background' }, s.background) : null, h('div', { class: 'zg-pgauth__c' }, h(C.AuthLayout, { title: p.title, subtitle: p.subtitle, logo: s.logo }, ...body)));
+} };
+T.PageStatus = { slots: ['code', 'message', 'action'], render: ({ C, h, props: p, slots: s }) => h(C.StatusPage, { kind: p.kind, title: p.title, description: p.description, onAction: p.onAction, actionLabel: p.actionLabel, notifyLabel: p.notifyLabel, emailLabel: p.emailLabel, onNotify: p.onNotify, codeNode: s.code || undefined, messageNode: s.message || undefined, actionNode: s.action || undefined }) };
+
+export const pages = T;

package/src/meta/README.md

@@ -0,0 +1,29 @@
+# Component API metadata
+
+One file per group (`typography`, `layout`, `actions`, `forms`, `data`, `feedback`, `overlay`, `navigation`, `media`, `domain`, `pages`). They are the single source of truth for the docs props tables, `dist/manifest.json`, `llms.txt` and the MCP server.
+
+```js
+export default {
+  Button: {
+    description: 'One sentence: what it is and when to use it.',
+    props: {
+      variant: { type: "'primary' | 'secondary' | 'ghost' | 'danger' | 'inverse' | 'tonal' | 'outlined' | 'text' | 'elevated'", values: ['primary', 'secondary', ...], default: 'secondary', description: 'Visual emphasis.' },
+      disabled: { type: 'boolean', default: false, description: 'Blocks interaction and dims the button.' },
+      modelValue: { type: 'string', model: true, description: 'Controlled value. Vue v-model, React modelValue + onChange.' },
+    },
+    slots: { default: 'Button label.', actions: 'Right side of the header.' },   // Vue slot name = React prop / children
+    events: { change: 'Called with the new value.', click: 'Native click.' },       // React: onChange / onClick
+    notes: ['Optional: gotchas, accessibility, composition tips, 1 sentence each.'],
+  },
+};
+```
+
+Rules
+- Document every prop the render code reads (`node scripts/props-extract.mjs Name` lists them; `onXxx` are events, put them in `events`). Do not invent props the code does not read.
+- Enums MUST list every allowed value in `values` and show them in `type`; give the real `default` (look at the `||`/`??` fallback in the code).
+- `type` is TypeScript style: `string`, `number`, `boolean`, `string[]`, `{ value: string; label: string }[]`, `'a' | 'b'`, `VNode`.
+- Props shared by many components (`size`) are documented on each component that supports it: `size: { type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'", values: [...], default: 'md' }`.
+- Page templates: document each slot with what it expects (see `site/docs-data/templates.ts`).
+- English, short, no filler.
+
+Check with `node scripts/check-meta.mjs`.

package/src/meta/actions.js

@@ -0,0 +1,161 @@
+// API metadata for the actions group. Format: see src/meta/README.md
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'];
+const sizeProp = (def = 'md', desc = 'Component size.') => ({ type: "'xs' | 'sm' | 'md' | 'lg' | 'xl'", values: SIZES, default: def, description: desc });
+const TONES = ['brand', 'sky', 'success', 'warning', 'danger', 'neutral'];
+const toneType = "'brand' | 'sky' | 'success' | 'warning' | 'danger' | 'neutral'";
+const icon = (desc = 'Icon name.') => ({ type: 'string', description: desc });
+
+export default {
+  Button: {
+    description: 'Primary action control with visual variants, tones, sizes, icons and a loading state.',
+    props: {
+      variant: { type: "'primary' | 'secondary' | 'ghost' | 'danger' | 'inverse' | 'tonal' | 'outlined' | 'text' | 'elevated'", values: ['primary', 'secondary', 'ghost', 'danger', 'inverse', 'tonal', 'outlined', 'text', 'elevated'], default: 'secondary', description: 'Visual emphasis. primary is the main call to action, danger is destructive, inverse is for dark surfaces.' },
+      tone: { type: toneType, values: TONES, description: 'Accent color applied to tonal, outlined, text and elevated variants.' },
+      size: sizeProp('md', 'Button height: xs 28px, sm 32px, md 40px, lg 48px, xl 56px.'),
+      icon: icon('Icon shown before the label.'),
+      iconRight: icon('Icon shown after the label.'),
+      loading: { type: 'boolean', default: false, description: 'Shows a spinner instead of the icon and disables the button.' },
+      disabled: { type: 'boolean', default: false, description: 'Blocks interaction and dims the button.' },
+      block: { type: 'boolean', default: false, description: 'Stretches the button to the full width of its container.' },
+    },
+    events: { click: 'Native click event. Not fired while disabled or loading.' },
+    slots: { default: 'Button label.' },
+    notes: ['Always renders type="button", so it never submits a form by itself.'],
+  },
+  IconButton: {
+    description: 'Square button with only an icon; use for toolbars and compact actions.',
+    props: {
+      icon: { type: 'string', required: true, description: 'Icon name.' },
+      label: { type: 'string', required: true, description: 'Accessible name (aria-label). Required because there is no visible text.' },
+      size: sizeProp('md', 'Button size: xs 28px, sm 32px, md 40px, lg 48px, xl 56px.'),
+      ghost: { type: 'boolean', default: false, description: 'Transparent background until hover.' },
+    },
+    events: { click: 'Native click event.' },
+  },
+  Pressable: {
+    description: 'Unstyled pressable wrapper that makes any content a button with press feedback.',
+    props: {
+      as: { type: 'string', default: 'button', description: 'HTML tag. type="button" is set only when this is button.' },
+      label: { type: 'string', description: 'Accessible name (aria-label).' },
+      disabled: { type: 'boolean', default: false, description: 'Blocks interaction.' },
+    },
+    events: { click: 'Native click event.' },
+    slots: { default: 'Pressable content.' },
+    notes: ['For a non-button tag add role and keyboard handling yourself.'],
+  },
+  Fab: {
+    description: 'Floating action button for the main action of a screen; extended when a label is given.',
+    props: {
+      icon: { type: 'string', default: 'plus', description: 'Icon name.' },
+      label: { type: 'string', description: 'Text next to the icon (extended FAB) and the accessible name.' },
+      size: sizeProp('md', 'Button height: xs 36px, sm 44px, md 56px, lg 64px, xl 72px.'),
+    },
+    events: { click: 'Native click event.' },
+    notes: ['Always pass label: it is the accessible name. Without it the button falls back to the icon name as aria-label (for example "plus"), which is rarely a good description.'],
+  },
+  CopyButton: {
+    description: 'Button that copies a value to the clipboard and briefly confirms with a check icon, or reports a failure.',
+    props: {
+      value: { type: 'string', required: true, description: 'Text copied to the clipboard.' },
+      label: { type: 'string', description: 'Button text. Defaults to "Copy", then "Copied" for 1.5s after a click.' },
+      variant: { type: "'primary' | 'secondary' | 'ghost' | 'danger' | 'inverse' | 'tonal' | 'outlined' | 'text' | 'elevated'", values: ['primary', 'secondary', 'ghost', 'danger', 'inverse', 'tonal', 'outlined', 'text', 'elevated'], default: 'secondary', description: 'Button variant, same values as Button.' },
+      size: sizeProp('sm', 'Button size.'),
+    },
+    events: { copy: 'Called with the value after it was written to the clipboard.', error: 'Called with the error when the clipboard is unavailable or rejects the write. The button turns red with "Copy failed" for 1.5s.' },
+    notes: ['Needs a secure context (https or localhost) for navigator.clipboard. The result ("Copied" or "Copy failed") is announced through an aria-live region.'],
+  },
+  ToggleGroup: {
+    description: 'Group of toggle buttons with single or multiple selection, optionally icon-only.',
+    props: {
+      options: { type: '{ value: string; label: string; icon?: string }[]', default: '[]', required: true, description: 'Buttons to render. label is also used as the tooltip.' },
+      modelValue: { type: 'string | string[]', model: true, description: 'Selected value, or array of values when multiple.' },
+      multiple: { type: 'boolean', default: false, description: 'Allows several pressed buttons; modelValue becomes an array.' },
+      iconOnly: { type: 'boolean', default: false, description: 'Hides labels and shows only icons.' },
+      allowEmpty: { type: 'boolean', default: false, description: 'Single mode only: clicking the pressed button deselects it and emits null.' },
+      size: sizeProp('md', 'Control size.'),
+    },
+    events: { change: 'Called with the new value (string), null when deselected with allowEmpty, or the new array when multiple.' },
+    notes: ['Each button exposes aria-pressed. In single mode clicking the active option keeps it selected.'],
+  },
+  SegmentedControl: {
+    description: 'Segmented switch for choosing exactly one of a few options.',
+    props: {
+      items: { type: '{ value: string; label: string }[]', default: '[]', required: true, description: 'Segments to render.' },
+      modelValue: { type: 'string', model: true, description: 'Value of the selected segment.' },
+      size: sizeProp('md', 'Control size. sm and md also have a dedicated compact style.'),
+    },
+    events: { change: 'Called with the value of the clicked segment.' },
+  },
+  FilterChips: {
+    description: 'Row of selectable filter chips with single or multiple selection.',
+    props: {
+      items: { type: '{ value: string; label: string }[]', default: '[]', required: true, description: 'Chips to render.' },
+      modelValue: { type: 'string | string[]', model: true, description: 'Selected value, or array of values when multi.' },
+      multi: { type: 'boolean', default: false, description: 'Allows several selected chips; modelValue becomes an array.' },
+      size: sizeProp('md', 'Chip size.'),
+    },
+    events: { change: 'Called with the new value, or the new array when multi. Toggles chips off in multi mode only.' },
+  },
+  Chip: {
+    description: 'Compact label with optional icon and remove button; use for statuses, filters and attributes.',
+    props: {
+      variant: { type: "'tonal' | 'outlined' | 'solid'", values: ['tonal', 'outlined', 'solid'], default: 'tonal', description: 'Visual style.' },
+      tone: { type: toneType, values: TONES, default: 'brand', description: 'Accent color. Unknown values fall back to brand.' },
+      size: sizeProp('md', 'Chip height: xs 22px, sm 26px, md 32px, lg 38px, xl 46px.'),
+      pill: { type: 'boolean', default: false, description: 'Fully rounded corners.' },
+      icon: icon('Icon shown before the label.'),
+    },
+    events: { close: 'Canonical. Called when the remove button is clicked. The button is shown only when close or remove is provided.', remove: 'Alias of close, matching Tag.' },
+    slots: { default: 'Chip label.' },
+  },
+  Tag: {
+    description: 'Small pill label, optionally removable; use for keywords and selected values.',
+    props: {
+      size: sizeProp('md', 'Tag height: xs 22px, sm 24px, md 28px, lg 34px, xl 40px.'),
+    },
+    events: { remove: 'Called when the x button is clicked. The button is shown only when remove or close is provided.', close: 'Alias of remove, matching Chip. Use one name across both components in your app (close is the canonical one).' },
+    slots: { default: 'Tag label.' },
+  },
+  Badge: {
+    description: 'Status badge with a colored tone and optional dot.',
+    props: {
+      tone: { type: "'brand' | 'success' | 'warning' | 'danger' | 'info'", values: ['brand', 'success', 'warning', 'danger', 'info'], description: 'Color. Omit for the neutral style.' },
+      dot: { type: 'boolean', default: false, description: 'Shows a status dot before the content.' },
+      size: sizeProp('md', 'Badge height: xs 18px, sm 20px, md 24px, lg 28px, xl 32px.'),
+    },
+    slots: { default: 'Badge content.' },
+    notes: ['Badge uses info for blue; Chip and Button use the tone name sky instead.'],
+  },
+  ActionRail: {
+    description: 'Floating vertical or horizontal rail of icon buttons with a highlighted active item.',
+    props: {
+      items: { type: '{ value?: string; icon?: string; label?: string; separator?: boolean }[]', default: '[]', required: true, description: 'Rail entries. An item with separator: true renders a divider instead of a button.' },
+      value: { type: 'string', description: 'Value of the active item. Changed via the change event.' },
+      size: sizeProp('md', 'Button size inside the rail.'),
+    },
+    events: { change: 'Called with the value of the clicked item.' },
+    notes: ['Items other than the active one are shown as ghost buttons; label is the accessible name.'],
+  },
+  ActionCard: {
+    description: 'Card with a title and built-in collapse, refresh and remove controls.',
+    props: {
+      title: { type: 'string', required: true, description: 'Card title.' },
+      subtitle: { type: 'string', description: 'Text under the title.' },
+      collapsed: { type: 'boolean', description: 'Controlled collapsed state. When omitted the card keeps it internally.' },
+      loading: { type: 'boolean', description: 'Controlled refresh spinner. When omitted, Refresh shows the spinner for 1.8s by itself.' },
+      size: sizeProp('md', 'Card padding and font size.'),
+    },
+    events: { collapse: 'Called with the new collapsed boolean when the collapse button is clicked.', refresh: 'Refresh button clicked. Pass loading to show your own spinner.', remove: 'Remove button clicked; the card hides itself afterwards.' },
+    slots: { default: 'Card body. Hidden while collapsed.' },
+    notes: ['With collapsed set, update it from the collapse event, otherwise the card will not toggle.', 'Removing hides the card until the component is remounted; also remove it from your data on the remove event.'],
+  },
+  NotificationBell: {
+    description: 'Bell icon button with an unread counter and a dropdown list of notifications.',
+    props: {
+      items: { type: '{ id: string | number; title: string; message?: string; time?: string; read?: boolean }[]', default: '[]', description: 'Notifications. Items without read: true count as unread and show a dot.' },
+      size: sizeProp('md', 'Bell button size.'),
+    },
+    events: { read: 'Called with the item id when an unread item is clicked.', markAllRead: 'Called when "Mark all read" is clicked (shown while something is unread).', select: 'Called with the item when any item is clicked.' },
+    notes: ['If you handle read or markAllRead the component is controlled: it trusts only the read flags in items, so update them in your state. Without these handlers it marks items read internally.', 'The dropdown opens and closes internally, and closes on outside click or Escape.'],
+  },
+};