@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/layout/PageHeader.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    title: string;
+    subtitle?: string;
+    /** Optional eyebrow text shown above the title (small, uppercase). */
+    eyebrow?: string;
+    /** 'md' = list-page title (default); 'sm' = dense tool-page title. */
+    size?: 'md' | 'sm';
+    /** Before the title: an icon tile or an avatar. */
+    leading?: Snippet;
+    /** Inline after the title text, vertically centred: a status tag. */
+    titleTrailing?: Snippet;
+    /** Slot for action buttons rendered on the right. Use `slot: "actions"`. */
+    actions?: Snippet;
+    /** A row under the title: search, filters, view switches. */
+    toolbar?: Snippet;
+    /** Default body slot rendered below the header (e.g., breadcrumbs, tabs). */
+    children?: Snippet;
+    hasChildren?: boolean;
+}
+declare const PageHeader: import("svelte").Component<Props, {}, "">;
+type PageHeader = ReturnType<typeof PageHeader>;
+export default PageHeader;

package/dist/widgets/layout/PanelHeader.svelte

@@ -0,0 +1,76 @@
+<!--
+  src/lib/widgets/layout/PanelHeader.svelte
+  NEW 2026-09-25 (shell new-look slice 1). The header row of a side panel
+  (thread, artifact, details): optional leading snippet (a back button or an
+  icon), a title with an optional subtitle, an actions snippet, and a close
+  button when `onclose` is set. On `./ui` only (no registry or manifest
+  entry). `PageHeader` stays the spec widget for full pages.
+
+  Quiet chrome: a hairline bottom border, the 13px/12px type rhythm, ghost
+  icon buttons with the accent/10 hover. Unnamed props (data-*, aria-*,
+  handlers) are spread on the <header>.
+
+  Updated 2026-09-27 (canon gaps 2): `closeTitle` sets the close button's
+  title tooltip. Default none, so nothing changes for existing callers.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { HTMLAttributes } from 'svelte/elements';
+  import { cn } from '../../utils.js';
+  import XIcon from '@lucide/svelte/icons/x';
+
+  interface Props extends Omit<HTMLAttributes<HTMLElement>, 'class' | 'children' | 'title'> {
+    class?: string;
+    title?: string;
+    subtitle?: string;
+    onclose?: () => void;
+    /** aria-label for the close button. */
+    closeLabel?: string;
+    /** title (tooltip) for the close button. None by default. */
+    closeTitle?: string;
+    leading?: Snippet;
+    actions?: Snippet;
+    /** Replaces `title` when given. */
+    children?: Snippet;
+  }
+
+  let {
+    class: className,
+    title,
+    subtitle,
+    onclose,
+    closeLabel = 'Close',
+    closeTitle,
+    leading,
+    actions,
+    children,
+    ...rest
+  }: Props = $props();
+</script>
+
+<header
+  {...rest}
+  class={cn('flex min-h-11 shrink-0 items-center gap-2 border-b border-ripple-border px-3 py-1.5', className)}
+>
+  {#if leading}<div class="flex shrink-0 items-center">{@render leading()}</div>{/if}
+  <div class="min-w-0 flex-1">
+    <h2 class="truncate text-[13px] font-medium leading-tight text-ripple-surface-foreground">
+      {#if children}{@render children()}{:else}{title}{/if}
+    </h2>
+    {#if subtitle}
+      <p class="truncate text-[12px] leading-tight text-ripple-muted-foreground">{subtitle}</p>
+    {/if}
+  </div>
+  {#if typeof actions === 'function'}<div class="flex shrink-0 items-center gap-0.5">{@render actions()}</div>{/if}
+  {#if onclose}
+    <button
+      type="button"
+      aria-label={closeLabel}
+      title={closeTitle}
+      onclick={() => onclose?.()}
+      class="inline-flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-ripple-muted-foreground outline-none transition-colors duration-150 ease-ripple-out hover:bg-ripple-accent/10 hover:text-ripple-surface-foreground focus-visible:ring-2 focus-visible:ring-ripple-ring/60"
+    >
+      <XIcon size={14} />
+    </button>
+  {/if}
+</header>

package/dist/widgets/layout/PanelHeader.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLElement>, 'class' | 'children' | 'title'> {
+    class?: string;
+    title?: string;
+    subtitle?: string;
+    onclose?: () => void;
+    /** aria-label for the close button. */
+    closeLabel?: string;
+    /** title (tooltip) for the close button. None by default. */
+    closeTitle?: string;
+    leading?: Snippet;
+    actions?: Snippet;
+    /** Replaces `title` when given. */
+    children?: Snippet;
+}
+declare const PanelHeader: import("svelte").Component<Props, {}, "">;
+type PanelHeader = ReturnType<typeof PanelHeader>;
+export default PanelHeader;

package/dist/widgets/layout/Section.svelte

@@ -0,0 +1,41 @@
+<!--
+  Section.svelte
+  Updated 2026-09-12: body gate is `hasChildren || children` with an optional
+  `children?.()` call, so a hand-written Svelte caller that passes children but no
+  `hasChildren` renders them. The spec renderer's `hasChildren` path is unchanged.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { cn } from '../../utils.js';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    title?: string;
+    description?: string;
+    children?: Snippet;
+    hasChildren?: boolean;
+  }
+
+  let {
+    id, class: className, style,
+    title, description, children, hasChildren = false
+  }: Props = $props();
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+</script>
+
+<section {id} class={cn('flex flex-col gap-3 py-4', className)} style={styleString}>
+  {#if title || description}
+    <header class="flex flex-col gap-0.5">
+      {#if title}<h2 class="text-base font-semibold tracking-tight">{title}</h2>{/if}
+      {#if description}<p class="text-sm text-muted-foreground">{description}</p>{/if}
+    </header>
+  {/if}
+  {#if hasChildren || children}
+    {@render children?.()}
+  {/if}
+</section>

package/dist/widgets/layout/Section.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    title?: string;
+    description?: string;
+    children?: Snippet;
+    hasChildren?: boolean;
+}
+declare const Section: import("svelte").Component<Props, {}, "">;
+type Section = ReturnType<typeof Section>;
+export default Section;

package/dist/widgets/layout/SectionHeader.svelte

@@ -0,0 +1,95 @@
+<!--
+  src/lib/widgets/layout/SectionHeader.svelte
+  NEW 2026-09-25 (shell new-look slice 1). The group label above a run of
+  ListRows: "Rooms 4 [+]". On `./ui` only (no registry or manifest entry).
+
+  Collapsible when `collapsible` or `ontoggle` is set: the label and count
+  become a disclosure <button aria-expanded> with a chevron. `open` is
+  bindable and defaults to true, so it works uncontrolled; `ontoggle(next)`
+  reports every flip for a host that keeps the state in a store. Pass
+  `controls` with the id of the region it shows and hides.
+
+  The region itself is the host's (`{#if open}` around the rows). Ripple's
+  Collapsible renders its own title trigger with no slot for a custom header,
+  so pairing the two means sharing `open` with Collapsible's `value` and
+  `hideChevron`; SectionHeader does not change Collapsible.
+
+  The `action` snippet (a "+" button, a menu) is a sibling of the toggle,
+  never inside it.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { HTMLAttributes } from 'svelte/elements';
+  import { cn } from '../../utils.js';
+  import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children' | 'ontoggle'> {
+    class?: string;
+    label?: string;
+    count?: number | string;
+    open?: boolean;
+    collapsible?: boolean;
+    ontoggle?: (open: boolean) => void;
+    /** id of the region this header shows and hides (aria-controls). */
+    controls?: string;
+    action?: Snippet;
+    /** Replaces `label` when given. */
+    children?: Snippet;
+  }
+
+  let {
+    class: className,
+    label,
+    count,
+    open = $bindable(true),
+    collapsible = false,
+    ontoggle,
+    controls,
+    action,
+    children,
+    ...rest
+  }: Props = $props();
+
+  const isToggle = $derived(collapsible || !!ontoggle);
+
+  function toggle() {
+    open = !open;
+    ontoggle?.(open);
+  }
+</script>
+
+{#snippet body()}
+  {#if isToggle}
+    <ChevronRightIcon
+      size={12}
+      aria-hidden="true"
+      class={cn('shrink-0 transition-transform duration-150 ease-ripple-out', open && 'rotate-90')}
+    />
+  {/if}
+  <span class="truncate">{#if children}{@render children()}{:else}{label}{/if}</span>
+  {#if count != null && count !== ''}
+    <span data-section-count class="shrink-0 tabular-nums opacity-70">{count}</span>
+  {/if}
+{/snippet}
+
+<div
+  {...rest}
+  class={cn('flex h-7 min-w-0 items-center gap-1 px-2 text-[12px] font-medium text-ripple-muted-foreground', className)}
+>
+  {#if isToggle}
+    <button
+      type="button"
+      aria-expanded={open}
+      aria-controls={controls}
+      onclick={toggle}
+      class="-mx-1 flex h-6 min-w-0 flex-1 cursor-pointer items-center gap-1 rounded-md px-1 text-left outline-none transition-colors duration-150 ease-ripple-out hover:text-ripple-surface-foreground focus-visible:ring-2 focus-visible:ring-ripple-ring/60"
+    >
+      {@render body()}
+    </button>
+  {:else}
+    <div class="flex min-w-0 flex-1 items-center gap-1">{@render body()}</div>
+  {/if}
+  {#if action}
+    <div class="flex shrink-0 items-center">{@render action()}</div>
+  {/if}
+</div>

package/dist/widgets/layout/SectionHeader.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children' | 'ontoggle'> {
+    class?: string;
+    label?: string;
+    count?: number | string;
+    open?: boolean;
+    collapsible?: boolean;
+    ontoggle?: (open: boolean) => void;
+    /** id of the region this header shows and hides (aria-controls). */
+    controls?: string;
+    action?: Snippet;
+    /** Replaces `label` when given. */
+    children?: Snippet;
+}
+declare const SectionHeader: import("svelte").Component<Props, {}, "open">;
+type SectionHeader = ReturnType<typeof SectionHeader>;
+export default SectionHeader;

package/dist/widgets/layout/Separator.svelte

@@ -0,0 +1,69 @@
+<!--
+  Separator.svelte — Ripple divider widget (horizontal / vertical).
+  Updated 2026-06-08 (design polish): a horizontal divider now carries a sensible
+  DEFAULT vertical margin (12px) so it always has breathing room instead of sitting
+  flush against the content above and below — the captain's "dividers too close"
+  complaint. The margin is applied via a zero-specificity `:where()` scoped rule, so
+  ANY margin utility passed through `class` (e.g. `my-6`, `mt-0`) still wins without
+  needing to route the default through `cn` at all (twMerge dedupes classes in one
+  class string; it cannot dedupe a class against a CSS rule, which is what this is).
+  A passed explicit margin is also detected and skips the default outright as a belt-and-suspenders.
+  Vertical orientation is unaffected (no default block margin; it gets a small
+  inline margin instead so a vertical rule in a row breathes too).
+-->
+<script lang="ts">
+  import { cn } from '../../utils.js';
+  import { Separator } from '../../components/ui/separator/index.js';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    orientation?: 'horizontal' | 'vertical';
+  }
+
+  let { id, class: className, style, orientation = 'horizontal' }: Props = $props();
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+
+  // Belt-and-suspenders: if the spec already states a margin, don't impose the
+  // default rhythm at all (lets `m-0` / `my-8` etc. take full control).
+  const hasExplicitMargin = $derived(
+    /(^|\s)-?m[trblxy]?-/.test(className ?? '')
+  );
+</script>
+
+<div
+  class="ripple-separator"
+  data-orientation={orientation}
+  data-explicit-margin={hasExplicitMargin ? 'true' : undefined}
+>
+  <Separator
+    {id}
+    {orientation}
+    class={cn(className)}
+    style={styleString}
+  />
+</div>
+
+<style>
+  /* Wrapper carries the default rhythm. `:where()` keeps specificity at 0 so any
+     margin utility the spec passes through `class` still wins. twMerge in `cn` does
+     not help here: the default is a CSS rule, not a class it could dedupe against. */
+  .ripple-separator {
+    display: contents;
+  }
+
+  /* Horizontal divider: comfortable vertical breathing room (12px each side). */
+  :where(.ripple-separator[data-orientation='horizontal']:not([data-explicit-margin])) > :global(*) {
+    margin-block: 0.75rem;
+  }
+
+  /* Vertical divider in a row: a little inline space so it doesn't kiss its
+     neighbours. */
+  :where(.ripple-separator[data-orientation='vertical']:not([data-explicit-margin])) > :global(*) {
+    margin-inline: 0.75rem;
+  }
+</style>

package/dist/widgets/layout/Separator.svelte.d.ts

@@ -0,0 +1,10 @@
+import { Separator } from '../../components/ui/separator/index.js';
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    orientation?: 'horizontal' | 'vertical';
+}
+declare const Separator: import("svelte").Component<Props, {}, "">;
+type Separator = ReturnType<typeof Separator>;
+export default Separator;

package/dist/widgets/layout/Sheet.svelte

@@ -0,0 +1,64 @@
+<!-- widgets/layout/Sheet.svelte — the `sheet` spec widget: a controlled slide-in panel over
+     ui/sheet. `open` (or `value`, which Ripple's `bind` writes) drives it; closing fires
+     `onchange(false)`. `side` picks the edge and `size` caps a left/right sheet's width
+     (Sheet.Content's max-w scale, default "sm"). An optional title/description header sits
+     above the padded children. -->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { SheetSize } from '../../components/ui/sheet/sheet-content.svelte';
+  import { cn } from '../../utils.js';
+  import * as Sheet from '../../components/ui/sheet/index.js';
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    /** Whether the sheet is open. Bind to state for controlled open/close. */
+    open?: boolean;
+    /** Alias for `open` — Ripple's `bind` writes to `value`, so accept it here too. */
+    value?: boolean;
+    /** Side the sheet slides in from. */
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    /** Max width of a left/right sheet from `sm` up: "sm" (default) … "4xl". */
+    size?: SheetSize;
+    title?: string;
+    description?: string;
+    children?: Snippet;
+    onchange?: (value?: unknown) => void;
+  }
+
+  let {
+    id, class: className, style, open, value, side = 'right', size,
+    title, description, children, onchange
+  }: Props = $props();
+
+  const isOpen = $derived(open ?? value ?? false);
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+
+  function handleOpenChange(v: boolean) {
+    onchange?.(v);
+  }
+</script>
+
+<Sheet.Root open={isOpen} onOpenChange={handleOpenChange}>
+  <Sheet.Content
+    {id}
+    {side}
+    {size}
+    class={cn(className)}
+    style={styleString}
+  >
+    {#if title || description}
+      <Sheet.Header>
+        {#if title}<Sheet.Title>{title}</Sheet.Title>{/if}
+        {#if description}<Sheet.Description>{description}</Sheet.Description>{/if}
+      </Sheet.Header>
+    {/if}
+    <div class="px-4 pb-4">
+      {@render children?.()}
+    </div>
+  </Sheet.Content>
+</Sheet.Root>

package/dist/widgets/layout/Sheet.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from 'svelte';
+import type { SheetSize } from '../../components/ui/sheet/sheet-content.svelte';
+import * as Sheet from '../../components/ui/sheet/index.js';
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    /** Whether the sheet is open. Bind to state for controlled open/close. */
+    open?: boolean;
+    /** Alias for `open` — Ripple's `bind` writes to `value`, so accept it here too. */
+    value?: boolean;
+    /** Side the sheet slides in from. */
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    /** Max width of a left/right sheet from `sm` up: "sm" (default) … "4xl". */
+    size?: SheetSize;
+    title?: string;
+    description?: string;
+    children?: Snippet;
+    onchange?: (value?: unknown) => void;
+}
+declare const Sheet: import("svelte").Component<Props, {}, "">;
+type Sheet = ReturnType<typeof Sheet>;
+export default Sheet;

package/dist/widgets/layout/Sidebar.svelte

@@ -0,0 +1,146 @@
+<!-- Updated 2026-07-08: typed getIcon's Lucide lookup as a Svelte Component (was unknown → narrowed to {} at the render slot, failing svelte-check). -->
+<script lang="ts">
+  import { safeUrl } from '@ripple-ui/core';
+  import type { Snippet } from 'svelte';
+  import { cn } from '../../utils.js';
+  import * as icons from '@lucide/svelte';
+
+  interface NavItem {
+    label: string;
+    /** Optional lucide icon name (kebab-case, e.g. "home", "settings"). */
+    icon?: string;
+    href?: string;
+    /** Group label — items sharing the same group render under it. */
+    group?: string;
+    /** When true, render as the active/selected item. */
+    active?: boolean;
+    /** Optional badge text (e.g., a count). */
+    badge?: string;
+    /** Optional value used by on_select handler / state binding. */
+    value?: string;
+  }
+
+  interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    title?: string;
+    items?: NavItem[];
+    /** Currently active value (matched against item.value). */
+    value?: string;
+    /** Footer slot (e.g., user pill). */
+    footer?: Snippet;
+    /** Emitted when a non-href item is clicked, with item.value. */
+    onchange?: (value?: unknown) => void;
+  }
+
+  let {
+    id, class: className, style,
+    title, items = [], value, footer, onchange
+  }: Props = $props();
+
+  const styleString = $derived(
+    style ? Object.entries(style).map(([k, v]) => `${k}:${v}`).join(';') : undefined
+  );
+
+  // Group items: items sharing `group` cluster together; default group is "".
+  const grouped = $derived.by(() => {
+    const groups = new Map<string, NavItem[]>();
+    for (const item of items) {
+      const key = item.group ?? '';
+      const list = groups.get(key) ?? [];
+      list.push(item);
+      groups.set(key, list);
+    }
+    return Array.from(groups.entries());
+  });
+
+  function getIcon(name?: string) {
+    if (!name) return null;
+    const camel = name
+      .split('-')
+      .map((p, i) => (i === 0 ? p[0]!.toUpperCase() + p.slice(1) : p[0]!.toUpperCase() + p.slice(1)))
+      .join('');
+    return ((icons as unknown) as Record<string, import('svelte').Component<any, any, any>>)[camel] ?? null;
+  }
+
+  function isActive(item: NavItem): boolean {
+    if (item.active) return true;
+    if (value !== undefined && item.value !== undefined) return value === item.value;
+    return false;
+  }
+
+  function handleClick(item: NavItem) {
+    if (item.value !== undefined) onchange?.(item.value);
+  }
+</script>
+
+<aside
+  {id}
+  class={cn(
+    'flex flex-col gap-3 border-r border-border bg-card/40 p-3',
+    'w-56 shrink-0 h-full',
+    className
+  )}
+  style={styleString}
+>
+  {#if title}
+    <div class="px-2 py-1 text-sm font-semibold tracking-tight">{title}</div>
+  {/if}
+
+  <nav class="flex flex-col gap-4">
+    {#each grouped as [groupName, list] (groupName)}
+      <div class="flex flex-col gap-0.5">
+        {#if groupName}
+          <div class="px-2 pt-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground">
+            {groupName}
+          </div>
+        {/if}
+        {#each list as item, i (item.label + i)}
+          {@const ItemIcon = getIcon(item.icon)}
+          {@const active = isActive(item)}
+          {#if item.href}
+            <a
+              href={safeUrl(item.href)}
+              class={cn(
+                'flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',
+                active
+                  ? 'bg-muted text-foreground font-medium'
+                  : 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'
+              )}
+            >
+              {#if ItemIcon}<ItemIcon size={15} />{/if}
+              <span class="flex-1 truncate">{item.label}</span>
+              {#if item.badge}
+                <span class="rounded-full bg-muted px-1.5 py-0.5 text-[10px] tabular-nums">{item.badge}</span>
+              {/if}
+            </a>
+          {:else}
+            <button
+              type="button"
+              onclick={() => handleClick(item)}
+              class={cn(
+                'flex items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors text-left',
+                active
+                  ? 'bg-muted text-foreground font-medium'
+                  : 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'
+              )}
+            >
+              {#if ItemIcon}<ItemIcon size={15} />{/if}
+              <span class="flex-1 truncate">{item.label}</span>
+              {#if item.badge}
+                <span class="rounded-full bg-muted px-1.5 py-0.5 text-[10px] tabular-nums">{item.badge}</span>
+              {/if}
+            </button>
+          {/if}
+        {/each}
+      </div>
+    {/each}
+  </nav>
+
+  {#if typeof footer === 'function'}
+    <div class="mt-auto pt-2 border-t border-border">
+      {@render footer()}
+    </div>
+  {/if}
+</aside>

package/dist/widgets/layout/Sidebar.svelte.d.ts

@@ -0,0 +1,31 @@
+import type { Snippet } from 'svelte';
+interface NavItem {
+    label: string;
+    /** Optional lucide icon name (kebab-case, e.g. "home", "settings"). */
+    icon?: string;
+    href?: string;
+    /** Group label — items sharing the same group render under it. */
+    group?: string;
+    /** When true, render as the active/selected item. */
+    active?: boolean;
+    /** Optional badge text (e.g., a count). */
+    badge?: string;
+    /** Optional value used by on_select handler / state binding. */
+    value?: string;
+}
+interface Props {
+    id?: string;
+    class?: string;
+    style?: Record<string, string>;
+    title?: string;
+    items?: NavItem[];
+    /** Currently active value (matched against item.value). */
+    value?: string;
+    /** Footer slot (e.g., user pill). */
+    footer?: Snippet;
+    /** Emitted when a non-href item is clicked, with item.value. */
+    onchange?: (value?: unknown) => void;
+}
+declare const Sidebar: import("svelte").Component<Props, {}, "">;
+type Sidebar = ReturnType<typeof Sidebar>;
+export default Sidebar;