@lostgradient/cinder 0.2.0 → 0.3.0

package/src/_internal/tree-registry.svelte.ts

@@ -13,11 +13,21 @@ export type TreeNodeRegistration = {
   readonly disabled: boolean;
   selectionScopeIds?: () => readonly string[] | undefined;
   isBranch: () => boolean;
+  bulkExpandable?: () => boolean;
   label: () => string;
   /** DOM-focus the outer role="treeitem" element. */
   focus: () => void;
 };
 
+export type TreeVisibilityCandidate = {
+  id: string;
+  label: string;
+  parentId: string | null;
+  level: number;
+};
+
+export type TreeVisibilityPredicate = (candidate: TreeVisibilityCandidate) => boolean;
+
 /**
  * Reactive registry for tree nodes. Tracks registration order (DOM mount
  * order), parent/child relationships, and computes a flat visible-order list
@@ -30,6 +40,10 @@ export class TreeRegistry {
   /** Ordered child lists, keyed by parentId (null = root level). */
   readonly #children = new SvelteMap<string | null, string[]>();
 
+  get size(): number {
+    return this.#nodes.size;
+  }
+
   register(node: TreeNodeRegistration): () => void {
     if (this.#nodes.has(node.id)) {
       throw new Error(
@@ -71,18 +85,27 @@ export class TreeRegistry {
 
   /**
    * Returns the flat list of node ids in DFS visible order, respecting the
-   * current expansion state. Collapsed subtrees are excluded entirely.
+   * current expansion state. Collapsed subtrees are excluded entirely unless a
+   * filter predicate is supplied, in which case matching nodes and their
+   * ancestors are retained.
    */
-  getVisible(expandedIds: readonly string[]): string[] {
+  getVisible(
+    expandedIds: readonly string[],
+    visibilityPredicate?: TreeVisibilityPredicate,
+  ): string[] {
     const result: string[] = [];
     const expandedSet = new Set(expandedIds);
+    const retainedIds = visibilityPredicate
+      ? this.#retainedIdsForPredicate(visibilityPredicate)
+      : undefined;
 
     const visit = (parentId: string | null): void => {
       const childIds = this.#orderedChildren(parentId);
       for (const id of childIds) {
+        if (retainedIds && !retainedIds.has(id)) continue;
         result.push(id);
         const node = this.#nodes.get(id);
-        if (node?.isBranch() && expandedSet.has(id)) {
+        if (node?.isBranch() && (expandedSet.has(id) || retainedIds?.has(id))) {
           visit(id);
         }
       }
@@ -92,6 +115,32 @@ export class TreeRegistry {
     return result;
   }
 
+  #retainedIdsForPredicate(visibilityPredicate: TreeVisibilityPredicate): Set<string> {
+    const retainedIds = new Set<string>();
+
+    for (const [id, node] of this.#nodes) {
+      if (
+        !visibilityPredicate({
+          id,
+          label: node.label(),
+          parentId: node.parentId,
+          level: node.level,
+        })
+      ) {
+        continue;
+      }
+
+      retainedIds.add(id);
+      let parentId = node.parentId;
+      while (parentId !== null) {
+        retainedIds.add(parentId);
+        parentId = this.parentOf(parentId) ?? null;
+      }
+    }
+
+    return retainedIds;
+  }
+
   getNode(id: string): TreeNodeRegistration | undefined {
     return this.#nodes.get(id);
   }
@@ -122,6 +171,41 @@ export class TreeRegistry {
     return result;
   }
 
+  getAllBranchIds(options: { bulkOnly?: boolean } = {}): string[] {
+    const result: string[] = [];
+
+    const visit = (parentId: string | null): void => {
+      for (const id of this.#orderedChildren(parentId)) {
+        const node = this.#nodes.get(id);
+        if (!node?.isBranch()) continue;
+        if (!options.bulkOnly || this.isBulkExpandableBranch(id)) {
+          result.push(id);
+        }
+        visit(id);
+      }
+    };
+
+    visit(null);
+    return result;
+  }
+
+  isBulkExpandableBranch(id: string): boolean {
+    const node = this.#nodes.get(id);
+    return Boolean(node?.isBranch() && (node.bulkExpandable?.() ?? true));
+  }
+
+  ancestorsOf(id: string): string[] {
+    const result: string[] = [];
+    let parentId = this.parentOf(id);
+
+    while (parentId !== null && parentId !== undefined) {
+      result.push(parentId);
+      parentId = this.parentOf(parentId);
+    }
+
+    return result;
+  }
+
   siblingsOf(id: string): string[] {
     const node = this.#nodes.get(id);
     if (!node) return [];
@@ -137,8 +221,9 @@ export class TreeRegistry {
     prefix: string,
     currentId: string,
     expandedIds: readonly string[],
+    visibilityPredicate?: TreeVisibilityPredicate,
   ): string | undefined {
-    const visible = this.getVisible(expandedIds);
+    const visible = this.getVisible(expandedIds, visibilityPredicate);
     const lower = prefix.toLowerCase();
     const startIndex = visible.indexOf(currentId);
 

package/src/_internal/use-virtualizer.svelte.ts

@@ -0,0 +1,226 @@
+import { Virtualizer, type ScrollToOptions, type VirtualItem } from '@tanstack/virtual-core';
+import type { Attachment } from 'svelte/attachments';
+import { createSubscriber } from 'svelte/reactivity';
+
+export type TreeVirtualizerOptions = {
+  getScrollElement: () => HTMLElement | null;
+  getCount: () => number;
+  getItemKey: (index: number) => string | number;
+  getEstimatedSize: () => number;
+  getOverscan: () => number;
+  getInitialHeight: () => number;
+};
+
+export class TreeVirtualizer {
+  #virtualizer: Virtualizer<HTMLElement, HTMLElement> | null = null;
+  #scrollElement: HTMLElement | null = null;
+  #update: () => void = () => {};
+  #subscribe: () => void;
+
+  constructor(readonly options: TreeVirtualizerOptions) {
+    this.#subscribe = createSubscriber((update) => {
+      if (typeof window === 'undefined') return;
+
+      this.#update = update;
+      this.#virtualizer = new Virtualizer(this.#buildOptions());
+      const cleanup = this.#virtualizer._didMount();
+      this.#virtualizer._willUpdate();
+      update();
+
+      return () => {
+        cleanup();
+        this.#virtualizer = null;
+      };
+    });
+  }
+
+  get virtualItems(): VirtualItem[] {
+    this.#subscribe();
+    this.#syncOptions();
+    const fallbackItems = this.#fallbackVirtualItems();
+    const virtualizerItems = this.#virtualizer?.getVirtualItems();
+    const items = this.#shouldUseFallbackVirtualItems(virtualizerItems, fallbackItems)
+      ? fallbackItems
+      : (virtualizerItems ?? fallbackItems);
+    return items.map((item) => ({ ...item }));
+  }
+
+  get totalSize(): number {
+    this.#subscribe();
+    this.#syncOptions();
+    return (
+      this.#virtualizer?.getTotalSize() ?? this.options.getCount() * this.options.getEstimatedSize()
+    );
+  }
+
+  setScrollElement(element: HTMLElement | null): void {
+    if (this.#scrollElement === element) return;
+
+    this.#scrollElement = element;
+    this.#syncOptions();
+    this.#update();
+  }
+
+  scrollElement: Attachment<HTMLElement> = (node) => {
+    this.setScrollElement(node);
+
+    return () => {
+      if (this.#scrollElement === node) {
+        this.setScrollElement(null);
+      }
+    };
+  };
+
+  measureElement: Attachment<HTMLElement> = (node) => {
+    this.#syncOptions();
+    this.#virtualizer?.measureElement(node);
+    return () => this.#virtualizer?.measureElement(null);
+  };
+
+  scrollToIndex(index: number, options: ScrollToOptions = { align: 'auto' }): void {
+    this.#subscribe();
+    this.#syncOptions();
+    const element = this.#getScrollElement();
+    const shouldUseFallbackScroll = Boolean(
+      element && (!this.#virtualizer || element.clientHeight === 0),
+    );
+
+    this.#virtualizer?.scrollToIndex(index, options);
+    if (!element || !shouldUseFallbackScroll) return;
+
+    element.scrollTop = Math.max(0, index * Math.max(1, this.options.getEstimatedSize()));
+    element.dispatchEvent(new Event('scroll'));
+  }
+
+  #syncOptions(): void {
+    if (!this.#virtualizer) return;
+    this.#virtualizer.setOptions(this.#buildOptions());
+    this.#virtualizer._willUpdate();
+  }
+
+  #getScrollElement = (): HTMLElement | null =>
+    this.#scrollElement ?? this.options.getScrollElement();
+
+  #buildOptions() {
+    return {
+      count: this.options.getCount(),
+      getScrollElement: this.#getScrollElement,
+      getItemKey: this.options.getItemKey,
+      estimateSize: () => this.options.getEstimatedSize(),
+      overscan: this.#overscan(),
+      initialRect: { width: 0, height: this.options.getInitialHeight() },
+      observeElementRect: this.#observeElementRect,
+      observeElementOffset: this.#observeElementOffset,
+      scrollToFn: this.#scrollToOffset,
+      measureElement: this.#measureElement,
+      onChange: () => this.#update(),
+      indexAttribute: 'data-cinder-virtual-index',
+    };
+  }
+
+  #scrollToOffset = (
+    offset: number,
+    { adjustments = 0, behavior }: { adjustments?: number; behavior?: ScrollBehavior },
+    instance: Virtualizer<HTMLElement, HTMLElement>,
+  ): void => {
+    const element = instance.scrollElement;
+    if (!element) return;
+
+    const top = offset + adjustments;
+    if (typeof element.scrollTo === 'function') {
+      element.scrollTo(behavior ? { top, behavior } : { top });
+      return;
+    }
+
+    element.scrollTop = top;
+  };
+
+  #observeElementRect = (
+    instance: Virtualizer<HTMLElement, HTMLElement>,
+    callback: (rect: { width: number; height: number }) => void,
+  ): (() => void) => {
+    const element = instance.scrollElement;
+    if (!element) return () => {};
+
+    const notify = (): void => {
+      const rect = element.getBoundingClientRect();
+      callback({
+        width: rect.width,
+        height: rect.height || element.clientHeight || this.options.getInitialHeight(),
+      });
+    };
+
+    notify();
+    if (typeof ResizeObserver === 'undefined') return () => {};
+
+    const observer = new ResizeObserver(notify);
+    observer.observe(element);
+    return () => observer.disconnect();
+  };
+
+  #measureElement = (element: HTMLElement): number => {
+    const rect = element.getBoundingClientRect();
+    return rect.height || this.options.getEstimatedSize();
+  };
+
+  #fallbackVirtualItems(): VirtualItem[] {
+    const count = this.options.getCount();
+    if (count === 0) return [];
+
+    const size = Math.max(1, this.options.getEstimatedSize());
+    const overscan = this.#overscan();
+    const scrollTop = this.#getScrollElement()?.scrollTop ?? 0;
+    const visibleCount = Math.ceil(this.options.getInitialHeight() / size);
+    const startIndex = Math.max(0, Math.floor(scrollTop / size) - overscan);
+    const itemCount = Math.min(count - startIndex, visibleCount + overscan * 2);
+    return Array.from({ length: itemCount }, (_, offset) => {
+      const index = startIndex + offset;
+      return {
+        key: this.options.getItemKey(index),
+        index,
+        start: index * size,
+        end: (index + 1) * size,
+        size,
+        lane: 0,
+      };
+    });
+  }
+
+  #shouldUseFallbackVirtualItems(
+    virtualizerItems: readonly VirtualItem[] | undefined,
+    fallbackItems: readonly VirtualItem[],
+  ): boolean {
+    if (!virtualizerItems || fallbackItems.length === 0) {
+      return false;
+    }
+
+    if (virtualizerItems.length === 0) return true;
+
+    const scrollTop = this.#getScrollElement()?.scrollTop ?? 0;
+    if (scrollTop <= 0) return false;
+
+    const firstVirtualizerIndex = virtualizerItems[0]?.index ?? 0;
+    const firstFallbackIndex = fallbackItems[0]?.index ?? 0;
+    return Math.abs(firstVirtualizerIndex - firstFallbackIndex) > 1;
+  }
+
+  #overscan(): number {
+    return Math.max(0, this.options.getOverscan());
+  }
+
+  #observeElementOffset = (
+    instance: Virtualizer<HTMLElement, HTMLElement>,
+    callback: (offset: number, isScrolling: boolean) => void,
+  ): (() => void) => {
+    const element = instance.scrollElement;
+    if (!element) return () => {};
+
+    const notify = (): void => {
+      callback(element.scrollTop, true);
+      this.#update();
+    };
+    callback(element.scrollTop, false);
+    element.addEventListener('scroll', notify, { passive: true });
+    return () => element.removeEventListener('scroll', notify);
+  };
+}

package/src/_internal/virtual-item.ts

@@ -0,0 +1 @@
+export type { VirtualItem } from '@tanstack/virtual-core';

package/src/components/_timeline-item/index.ts

@@ -0,0 +1,5 @@
+import TimelineItem from './timeline-item.svelte';
+
+export default TimelineItem;
+export type { TimelineItemProps } from './timeline-item.types.ts';
+export { TimelineItem };

package/src/components/_tree-expand-all/index.ts

@@ -0,0 +1,5 @@
+import TreeExpandAll from './tree-expand-all.svelte';
+
+export default TreeExpandAll;
+export type { TreeExpandAllProps } from './tree-expand-all.types.ts';
+export { TreeExpandAll };

package/src/components/_tree-expand-all/tree-expand-all.svelte

@@ -0,0 +1,83 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status stable
+   * @purpose Context control for expanding or collapsing all registered static Tree branches.
+   * @tag tree
+   * @tag expansion
+   * @useWhen Adding expand-all and collapse-all controls to a Tree selectionControls snippet.
+   * @useWhen Expanding registered static Tree branches without placing controls inside role="tree".
+   * @avoidWhen Rendering outside a Tree component — it requires Tree selectionControls context.
+   * @avoidWhen Triggering async lazy loading for every branch; bulk expansion skips loadChildren branches.
+   * @related tree, tree-item
+   */
+  export type { TreeExpandAllProps } from './tree-expand-all.types.ts';
+</script>
+
+<script lang="ts">
+  import type { TreeContext } from '../../_internal/tree-context.ts';
+  import { getTreeContext } from '../../_internal/tree-context.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { TreeExpandAllProps } from './tree-expand-all.types.ts';
+
+  let {
+    label = 'Tree expansion',
+    expandAllLabel = 'Expand all',
+    expandOneLevelLabel = 'Expand one level',
+    collapseAllLabel = 'Collapse all',
+    safetyThreshold = 500,
+    class: className,
+  }: TreeExpandAllProps = $props();
+
+  const context: TreeContext = getTreeContext();
+
+  const expandDisabled = $derived(context.expandableBranchCount === 0);
+  const collapseDisabled = $derived(!context.hasExpandedItems);
+  const showSafetyValve = $derived(context.expandableBranchCount > safetyThreshold);
+
+  function expandAll(): void {
+    if (!expandDisabled) void context.expandAll();
+  }
+
+  function expandOneLevel(): void {
+    if (!expandDisabled) context.expandOneLevel();
+  }
+
+  function collapseAll(): void {
+    if (!collapseDisabled) context.collapseAll();
+  }
+</script>
+
+<div class={classNames('cinder-tree-expand-all', className)}>
+  <span class="cinder-tree-expand-all__label">{label}</span>
+  {#if showSafetyValve}
+    <button
+      type="button"
+      class="cinder-tree-expand-all__button"
+      aria-label={`${expandOneLevelLabel}: ${label}`}
+      disabled={expandDisabled}
+      onclick={expandOneLevel}
+    >
+      {expandOneLevelLabel}
+    </button>
+  {/if}
+  <button
+    type="button"
+    class="cinder-tree-expand-all__button"
+    aria-label={`${expandAllLabel}: ${label}`}
+    disabled={expandDisabled}
+    onclick={expandAll}
+  >
+    {expandAllLabel}
+  </button>
+  <button
+    type="button"
+    class="cinder-tree-expand-all__button"
+    aria-label={`${collapseAllLabel}: ${label}`}
+    disabled={collapseDisabled}
+    onclick={collapseAll}
+  >
+    {collapseAllLabel}
+  </button>
+</div>

package/src/components/_tree-expand-all/tree-expand-all.types.ts

@@ -0,0 +1,15 @@
+/** Props for the TreeExpandAll component. */
+export type TreeExpandAllProps = {
+  /** Text label shown before the action buttons. */
+  label?: string;
+  /** Label for the full expand action. */
+  expandAllLabel?: string;
+  /** Label for the one-level expand action shown on large trees. */
+  expandOneLevelLabel?: string;
+  /** Label for the collapse-all action. */
+  collapseAllLabel?: string;
+  /** Branch count above which a one-level expand safety action is shown. */
+  safetyThreshold?: number;
+  /** Additional class merged with `.cinder-tree-expand-all`. */
+  class?: string;
+};

package/src/components/_visually-hidden-live-region.svelte

@@ -38,10 +38,20 @@
 
   let {
     message = '',
+    announcementSequence = 0,
     priority = 'polite',
     class: className,
   }: {
     message?: string;
+    /**
+     * Bump this (monotonically) to force a re-announcement of an identical
+     * `message`. In Svelte 5, assigning the same string to a `$state` is a no-op,
+     * so a consumer that announces the same text twice in a row (e.g. adding the
+     * same tag again) would not re-run this component's effect. Reading the
+     * sequence inside the effect registers it as a dependency, so incrementing it
+     * — even with `message` unchanged — re-fires the blank-then-set dance.
+     */
+    announcementSequence?: number;
     priority?: LiveRegionPriority;
     class?: string;
   } = $props();
@@ -69,6 +79,9 @@
   // then PERSISTS until the consumer changes it (no auto-clear of an active status).
   $effect(() => {
     const next = message;
+    // Read the sequence so it is tracked as a dependency: bumping it re-runs this
+    // effect even when `message` is byte-identical to the previous announcement.
+    void announcementSequence;
     const current = ++version;
 
     if (setTimeoutId) {

package/src/components/access-gate/README.md

@@ -0,0 +1,55 @@
+# AccessGate
+
+Authorization presentation gate for controls and sections that stay visible when
+the current user is missing an application scope or permission.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { AccessGate } from '@lostgradient/cinder/access-gate';
+  import { Button } from '@lostgradient/cinder/button';
+</script>
+
+<AccessGate granted={false} reason="Requires scope: workflows:cancel">
+  <Button label="Cancel workflow" />
+</AccessGate>
+
+<AccessGate
+  granted={false}
+  variant="section"
+  reason="Requires scope: storage:admin"
+  requirement="storage:admin"
+/>
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop          | Type                      | Required | Default    | Description                                                                                                                          |
+| ------------- | ------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`       | `string`                  | no       | —          | Custom class merged with the denied-state wrapper or section placeholder.                                                            |
+| `granted`     | `boolean`                 | yes      | —          | Whether the consumer-authorized action or section is available.                                                                      |
+| `reason`      | `string`                  | yes      | —          | Human-readable explanation shown to users and wired to assistive technology.                                                         |
+| `requirement` | `string`                  | no       | —          | Named scope, permission, or policy requirement shown in the section placeholder.                                                     |
+| `variant`     | `"inline"` \| `"section"` | no       | `"inline"` | Presentation mode.                                                                                                                   |
+| `children`    | `(opaque)`                | no       | —          | Gated content. Rendered untouched when access is granted. Not expressible in JSON Schema; see the component types for the signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->