@lostgradient/cinder 0.1.1 → 0.3.0

package/src/components/dropdown-item/dropdown-item.types.ts

@@ -1,10 +1,70 @@
 import type { Snippet } from 'svelte';
-import type { HTMLButtonAttributes } from 'svelte/elements';
+import type { HTMLAnchorAttributes, HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
+
 export type DropdownItemVariant = 'default' | 'danger';
-export type DropdownItemProps = Omit<HTMLButtonAttributes, 'class'> & {
+
+// The shared base carries the common HTML attribute surface — crucially the
+// event handlers (onclick/onkeydown/onfocus/…) — typed against the generic
+// `HTMLElement`. Both render paths (`<button>` and `<a>`) satisfy that, so a
+// consumer can attach an inline handler without TypeScript forcing it to
+// "prove" which branch it is on. Element-specific NON-event attributes live in
+// the two branches so the `href` ⇄ `type` discriminant stays real.
+type DropdownItemBase = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Visual style of the item. Use `danger` to signal a destructive action. Default `default`. */
   variant?: DropdownItemVariant;
+  /** When true, adds leading padding to align the item with items that have a leading icon or indicator. Default `false`. */
   inset?: boolean;
+  /** When true, the parent dropdown closes after this item is activated. Default `true`. */
   closeOnSelect?: boolean;
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children?: Snippet;
+  /** When true the item is inert: click is blocked and aria-disabled is set. */
+  disabled?: boolean | undefined;
 };
+
+/**
+ * Button variant — renders a `<button>`. Forwards every button-specific
+ * attribute (`name`, `value`, `form`, `formaction`, `formmethod`,
+ * `formnovalidate`, `formtarget`, `formenctype`, …) by subtracting the shared
+ * `HTMLElement` surface — which the base already provides with `HTMLElement`-typed
+ * event handlers — so a form-submitting menu item (`type="submit"` with `name`/
+ * `value`) keeps full typing without reintroducing the inline-handler
+ * contravariance trap. `disabled` is owned by the base (a managed click guard +
+ * aria-disabled), not the native attribute.
+ */
+export type DropdownItemButtonProps = DropdownItemBase &
+  Omit<HTMLButtonAttributes, keyof HTMLAttributes<HTMLElement> | 'class' | 'disabled' | 'type'> & {
+    href?: undefined;
+    /**
+     * Button type forwarded to the `<button>` element. Defaults to `"button"`.
+     *
+     * NOTE: `type="submit"` only submits a surrounding `<form>` when the menu
+     * stays inside that form's DOM subtree. DropdownMenu portals its panel to
+     * `document.body` on the non-popover fallback path, so a submit item is then
+     * NOT a form descendant and native submission is skipped. To submit a form
+     * from a portaled menu, set `form="<form-id>"` to associate the button with
+     * the form by id, or handle submission in `onclick`.
+     */
+    type?: 'button' | 'submit' | 'reset';
+  };
+
+/**
+ * Anchor variant — renders an `<a href>`. `disabled` blocks navigation and sets
+ * aria-disabled. Forwards every anchor-specific attribute (`target`, `rel`,
+ * `download`, `ping`, `hreflang`, `referrerpolicy`, …) by subtracting the shared
+ * `HTMLElement` surface — which the base already provides with `HTMLElement`-typed
+ * event handlers — so the inline-handler contravariance trap never reappears.
+ */
+export type DropdownItemAnchorProps = DropdownItemBase &
+  Omit<HTMLAnchorAttributes, keyof HTMLAttributes<HTMLElement> | 'class' | 'href'> & {
+    /**
+     * Destination URL. Any defined value — including an empty string — selects
+     * the anchor branch and renders an `<a>`. Omit `href` entirely to render a
+     * `<button>`.
+     */
+    href: string;
+    type?: undefined;
+  };
+
+export type DropdownItemProps = DropdownItemButtonProps | DropdownItemAnchorProps;

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

@@ -1,5 +1,10 @@
 import DropdownItem from './dropdown-item.svelte';
 
 export default DropdownItem;
-export type { DropdownItemProps, DropdownItemVariant } from './dropdown-item.types.ts';
+export type {
+  DropdownItemAnchorProps,
+  DropdownItemButtonProps,
+  DropdownItemProps,
+  DropdownItemVariant,
+} from './dropdown-item.types.ts';
 export { DropdownItem };

package/src/components/dropdown-label/README.md

@@ -16,7 +16,7 @@ snippet. The flat `@lostgradient/cinder/dropdown-label` subpath remains exported
 
 | Prop       | Type       | Required | Default | Description                                                                                                                |
 | ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       |                                                                                                                            |
+| `class`    | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
 | `children` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->

package/src/components/dropdown-label/dropdown-label.types.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type DropdownLabelProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children?: Snippet;
 };

package/src/components/dropdown-menu/README.md

@@ -16,7 +16,7 @@ snippet. The flat `@lostgradient/cinder/dropdown-menu` subpath remains exported
 
 | Prop       | Type       | Required | Default | Description                                                                                                                |
 | ---------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`    | `string`   | no       | —       |                                                                                                                            |
+| `class`    | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
 | `children` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 
 <!-- generated:props:end -->

package/src/components/dropdown-menu/dropdown-menu.types.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 export type DropdownMenuProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
   children?: Snippet;
 };

package/src/components/dropdown-separator/README.md

@@ -14,9 +14,9 @@ snippet. The flat `@lostgradient/cinder/dropdown-separator` subpath remains expo
 
 <!-- generated:props:start -->
 
-| Prop    | Type     | Required | Default | Description |
-| ------- | -------- | -------- | ------- | ----------- |
-| `class` | `string` | no       | —       |             |
+| Prop    | Type     | Required | Default | Description                                                    |
+| ------- | -------- | -------- | ------- | -------------------------------------------------------------- |
+| `class` | `string` | no       | —       | Additional class names merged with the component's root class. |
 
 <!-- generated:props:end -->
 

package/src/components/dropdown-separator/dropdown-separator.types.ts

@@ -1,4 +1,5 @@
 import type { HTMLAttributes } from 'svelte/elements';
 export type DropdownSeparatorProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
 };

package/src/components/dropdown-trigger/README.md

@@ -16,7 +16,7 @@ snippet. The flat `@lostgradient/cinder/dropdown-trigger` subpath remains export
 
 | Prop        | Type       | Required | Default | Description                                                                                                                |
 | ----------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`     | `string`   | no       | —       |                                                                                                                            |
+| `class`     | `string`   | no       | —       | Additional class names merged with the component's root class.                                                             |
 | `showCaret` | `boolean`  | no       | —       | Render the trailing disclosure caret. Defaults to true.                                                                    |
 | `children`  | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 

package/src/components/dropdown-trigger/dropdown-trigger.types.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLButtonAttributes } from 'svelte/elements';
 export type DropdownTriggerProps = Omit<HTMLButtonAttributes, 'class'> & {
+  /** Additional class names merged with the component's root class. */
   class?: string;
   /** Render the trailing disclosure caret. Defaults to true. */
   showCaret?: boolean;

package/src/components/empty-state/README.md

@@ -18,10 +18,10 @@ Placeholder layout for zero-data views, with optional illustration, heading, and
 
 | Prop           | Type                                   | Required | Default | Description                                                                                                                |
 | -------------- | -------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`        | `string`                               | no       | —       |                                                                                                                            |
-| `description`  | `string`                               | no       | —       |                                                                                                                            |
+| `class`        | `string`                               | no       | —       | Additional class merged onto the `.cinder-empty-state` root element.                                                       |
+| `description`  | `string`                               | no       | —       | Secondary descriptive text rendered as a paragraph below the title.                                                        |
 | `headingLevel` | `1` \| `2` \| `3` \| `4` \| `5` \| `6` | no       | `3`     | Heading level for the title element.                                                                                       |
-| `title`        | `string`                               | yes      | —       |                                                                                                                            |
+| `title`        | `string`                               | yes      | —       | Primary heading text rendered as a heading element at the configured `headingLevel`.                                       |
 | `action`       | `(opaque)`                             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `icon`         | `(opaque)`                             | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 

package/src/components/empty-state/empty-state.types.ts

@@ -2,8 +2,11 @@ import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 
 export type EmptyStateProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Primary heading text rendered as a heading element at the configured `headingLevel`. */
   title: string;
+  /** Secondary descriptive text rendered as a paragraph below the title. */
   description?: string;
+  /** Additional class merged onto the `.cinder-empty-state` root element. */
   class?: string;
   /**
    * Heading level for the title element.

package/src/components/event-stream-viewer/README.md

@@ -0,0 +1,147 @@
+# EventStreamViewer
+
+Dense append-only viewer for timestamped operational events. Use it for workflow run logs, job output streams, webhook traces, activity completion feeds, and other real-time or historical event consoles.
+
+## Overview
+
+EventStreamViewer renders a scrollable list of timestamped events, each with a severity tone, optional source label, a one-line summary, and optional expandable JSON details. It handles follow-latest scrolling (auto-scroll to bottom as events arrive), a paused state when the user scrolls away, filtering hooks, and copy actions. Empty, loading, disconnected, and truncated states are built in.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
+  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';
+
+  let events: StreamEvent[] = $state([]);
+</script>
+
+<EventStreamViewer {events} label="Workflow run events" connectionState="connected" />
+```
+
+### With filtering
+
+When you pass an `onfilter` callback, the viewer renders a search input. Your component is responsible for filtering the `events` array in response to the callback.
+
+```svelte
+<script lang="ts">
+  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
+  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';
+
+  let allEvents: StreamEvent[] = $state([]);
+  let query = $state('');
+
+  const filteredEvents = $derived(
+    query
+      ? allEvents.filter((e) => e.summary.toLowerCase().includes(query.toLowerCase()))
+      : allEvents,
+  );
+</script>
+
+<EventStreamViewer
+  events={filteredEvents}
+  filterQuery={query}
+  onfilter={(q) => {
+    query = q;
+  }}
+  label="Filtered event stream"
+/>
+```
+
+### With copy-visible action
+
+```svelte
+<script lang="ts">
+  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
+  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';
+
+  let events: StreamEvent[] = $state([]);
+
+  function handleCopyVisible(text: string) {
+    navigator.clipboard.writeText(text);
+  }
+</script>
+
+<EventStreamViewer {events} oncopyvisible={handleCopyVisible} label="Event stream" />
+```
+
+### Follow-latest with bindable state
+
+The `followLatest` prop is bindable. Bind it to read whether the viewer is paused or to programmatically resume following.
+
+```svelte
+<script lang="ts">
+  import { EventStreamViewer } from '@lostgradient/cinder/event-stream-viewer';
+  import type { StreamEvent } from '@lostgradient/cinder/event-stream-viewer';
+
+  let events: StreamEvent[] = $state([]);
+  let followLatest = $state(true);
+</script>
+
+<p>Status: {followLatest ? 'Following' : 'Paused'}</p>
+<EventStreamViewer {events} bind:followLatest label="Event stream" />
+```
+
+## Event structure
+
+Each event in the `events` array follows the `StreamEvent` type:
+
+```ts
+type StreamEvent = {
+  id: string; // Stable unique identifier (required)
+  datetime: string; // ISO 8601 datetime (required, used for machine-readable time)
+  timestamp?: string; // Human-readable label e.g. "14:32:01" (falls back to datetime)
+  severity?: 'debug' | 'info' | 'success' | 'warning' | 'error';
+  source?: string; // Origin label e.g. "worker-1", "payment-service"
+  summary: string; // One-line event description (required)
+  details?: unknown; // Optional JSON payload rendered in a collapsible JsonViewer
+};
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop              | Type                                                             | Required | Default | Description                                                                                                                                                                                                                                                              |
+| ----------------- | ---------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `class`           | `string`                                                         | no       | —       | Additional CSS classes applied to the root element.                                                                                                                                                                                                                      |
+| `connectionState` | `"connected"` \| `"connecting"` \| `"disconnected"` \| `"error"` | no       | —       | Current connection state. When provided, renders a ConnectionIndicator in the toolbar. Omit when the stream has no live transport.                                                                                                                                       |
+| `filterQuery`     | `string`                                                         | no       | —       | Current filter query value, for controlled usage. Pairs with `onfilter`.                                                                                                                                                                                                 |
+| `followLatest`    | `boolean`                                                        | no       | —       | When true, new events automatically scroll the list to the bottom. Set to false to pause follow-latest (e.g. while the user reads earlier events). Bindable so the parent can read the paused state the component sets internally.                                       |
+| `label`           | `string`                                                         | no       | —       | Accessible label for the event list region. Required for accessibility. Defaults to "Event stream".                                                                                                                                                                      |
+| `loading`         | `boolean`                                                        | no       | —       | Show a loading skeleton instead of the event list. Use while the first batch of events is in flight.                                                                                                                                                                     |
+| `truncated`       | `boolean`                                                        | no       | —       | Whether to show the "events were truncated" notice. This is a boolean flag, not a count: the viewer never slices `events` itself. Set it to `true` when you have already trimmed the array (e.g. capped retention) and want users to know earlier events are not shown.  |
+| `events`          | `(opaque)`                                                       | yes      | —       | Events to render in chronological order, oldest first. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                        |
+| `oncopyvisible`   | `(opaque)`                                                       | no       | —       | Callback fired when the user clicks the "Copy visible" toolbar action. Receives the text of all currently visible events. When omitted the copy action is hidden. Not expressible in JSON Schema; see the component types for the signature.                             |
+| `onfilter`        | `(opaque)`                                                       | no       | —       | Callback fired when the user updates the filter query in the toolbar's search field. The consumer is responsible for filtering `events` in response. When omitted the filter input is hidden. Not expressible in JSON Schema; see the component types for the signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+- `--cinder-event-stream-viewer-severity-color`
+<!-- generated:variables:end -->
+
+## Accessibility
+
+The viewer exposes a `role="log"` region with `aria-live="polite"` and `aria-atomic="false"` so screen readers announce newly appended events. The region is keyboard focusable (`tabindex="0"`) to support arrow-key scrolling.
+
+Each event's timestamp is wrapped in a `<time datetime="...">` element with the machine-readable ISO value, so assistive technology can parse the precise moment. The visible label is separate from the machine-readable `datetime` attribute.
+
+Severity tones are conveyed both visually (color bar, badge text) and through an `aria-label` on the badge element. Source labels and summary text are part of the document flow and are read naturally.
+
+The JSON details panel is toggled by a button with `aria-expanded` and `aria-controls`. Copy actions have descriptive `aria-label` attributes.
+
+A visually-hidden live region (always in the DOM, never removed with `{#if}`) announces copy confirmation to screen readers without double-announcing on the interactive buttons.
+
+See `event-stream-viewer.a11y.md` for the full accessibility contract.
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+This component composes `ConnectionIndicator`, `CopyButton`, and `JsonViewer` internally. They are not exposed as sub-namespace exports.
+
+<!-- generated:subcomponents:end -->