@lostgradient/cinder 0.1.0

package/src/components/json-schema-editor/property-list.svelte

@@ -0,0 +1,296 @@
+<script lang="ts" module>
+  import type { JsonSchemaValue } from './json-schema-editor-types.ts';
+
+  export type PropertyListProps = {
+    idPrefix: string;
+    properties: Record<string, JsonSchemaValue>;
+    required: string[];
+    path: string;
+    depth?: number;
+    readonly?: boolean;
+    onchange: (properties: Record<string, JsonSchemaValue>, required: string[]) => void;
+  };
+</script>
+
+<script lang="ts">
+  import Alert from '../alert/alert.svelte';
+  import Button from '../button/button.svelte';
+  import Chip from '../chip/chip.svelte';
+  import Input from '../input/input.svelte';
+  import PropertyEditor from './property-editor.svelte';
+
+  let {
+    idPrefix,
+    properties,
+    required,
+    path,
+    depth = 0,
+    readonly = false,
+    onchange,
+  }: PropertyListProps = $props();
+
+  const propertyNames = $derived(Object.keys(properties));
+  const requiredOnly = $derived(required.filter((name) => !propertyNames.includes(name)));
+
+  // Per-row draft names so a partial typed name doesn't reshape the parent.
+  let draftNames = $state<Record<string, string>>({});
+  let renameError = $state<string | null>(null);
+  let expanded = $state<Record<string, boolean>>({});
+
+  function getDraftName(key: string): string {
+    return draftNames[key] ?? key;
+  }
+
+  function uniqueNewKey(): string {
+    let suffix = 1;
+    let candidate = 'newField';
+    while (Object.prototype.hasOwnProperty.call(properties, candidate)) {
+      suffix += 1;
+      candidate = `newField${suffix}`;
+    }
+    return candidate;
+  }
+
+  function commitRename(oldKey: string) {
+    if (readonly) return;
+    const draft = getDraftName(oldKey).trim();
+    if (!draft) {
+      renameError = 'Property name cannot be empty';
+      return;
+    }
+    if (draft === oldKey) {
+      renameError = null;
+      return;
+    }
+    if (Object.prototype.hasOwnProperty.call(properties, draft)) {
+      renameError = `Duplicate property name: ${draft}`;
+      return;
+    }
+    renameError = null;
+
+    const next: Record<string, JsonSchemaValue> = {};
+    for (const k of propertyNames) {
+      next[k === oldKey ? draft : k] = properties[k]!;
+    }
+    const nextRequired = required.map((name) => (name === oldKey ? draft : name));
+
+    delete draftNames[oldKey];
+    if (expanded[oldKey]) {
+      expanded[draft] = true;
+      delete expanded[oldKey];
+    }
+    onchange(next, nextRequired);
+  }
+
+  function deleteProperty(key: string) {
+    if (readonly) return;
+    const next = { ...properties };
+    delete next[key];
+    const nextRequired = required.filter((name) => name !== key);
+    delete draftNames[key];
+    delete expanded[key];
+    onchange(next, nextRequired);
+  }
+
+  function moveProperty(key: string, direction: -1 | 1) {
+    if (readonly) return;
+    const index = propertyNames.indexOf(key);
+    const target = index + direction;
+    if (target < 0 || target >= propertyNames.length) return;
+
+    const reordered = [...propertyNames];
+    [reordered[index], reordered[target]] = [reordered[target]!, reordered[index]!];
+    const next: Record<string, JsonSchemaValue> = {};
+    for (const name of reordered) next[name] = properties[name]!;
+    onchange(next, required);
+  }
+
+  function toggleRequired(key: string) {
+    if (readonly) return;
+    const set = new Set(required);
+    if (set.has(key)) set.delete(key);
+    else set.add(key);
+    onchange(properties, [...set]);
+  }
+
+  function setPropertySchema(key: string, schema: JsonSchemaValue) {
+    if (readonly) return;
+    onchange({ ...properties, [key]: schema }, required);
+  }
+
+  function addProperty() {
+    if (readonly) return;
+    const key = uniqueNewKey();
+    onchange({ ...properties, [key]: { type: 'string' } }, required);
+    expanded[key] = true;
+  }
+
+  function summariseType(schema: JsonSchemaValue): string {
+    if (typeof schema === 'boolean') return schema ? 'true' : 'false';
+    const t = schema.type;
+    if (t === undefined) return 'any';
+    if (Array.isArray(t)) return t.join(' | ');
+    return t;
+  }
+
+  // ===== Required-only chip editing =====
+  let newRequiredOnlyName = $state('');
+
+  function addRequiredOnly() {
+    if (readonly) return;
+    const name = newRequiredOnlyName.trim();
+    if (!name) {
+      newRequiredOnlyName = '';
+      return;
+    }
+    if (required.includes(name)) {
+      newRequiredOnlyName = '';
+      return;
+    }
+    onchange(properties, [...required, name]);
+    newRequiredOnlyName = '';
+  }
+
+  function removeRequiredOnly(name: string) {
+    if (readonly) return;
+    onchange(
+      properties,
+      required.filter((entry) => entry !== name),
+    );
+  }
+</script>
+
+<div class="cinder-jse-property-list">
+  {#if renameError}
+    <Alert variant="error">{renameError}</Alert>
+  {/if}
+
+  {#if propertyNames.length === 0}
+    <p class="cinder-jse-property-list__empty">No properties yet.</p>
+  {/if}
+
+  {#each propertyNames as key (key)}
+    {@const isRequired = required.includes(key)}
+    {@const isOpen = expanded[key] === true}
+    {@const panelId = `${idPrefix}-${key}-panel`}
+    <!--
+      Custom disclosure (not <details>/<summary>) so the action buttons can
+      live as siblings of the trigger rather than nested inside it.
+      <button> inside <summary> creates an ARIA "interactive within
+      interactive" violation.
+    -->
+    <div class="cinder-jse-property-row" data-cinder-required={isRequired ? '' : undefined}>
+      <div class="cinder-jse-property-row__summary">
+        <button
+          type="button"
+          class="cinder-jse-property-row__trigger"
+          aria-expanded={isOpen}
+          aria-controls={panelId}
+          onclick={() => (expanded[key] = !isOpen)}
+        >
+          <span class="cinder-jse-property-row__chevron" aria-hidden="true">▸</span>
+          <span class="cinder-jse-property-row__name">{key}</span>
+          <span class="cinder-jse-property-row__type">{summariseType(properties[key] ?? {})}</span>
+        </button>
+        <span class="cinder-jse-property-row__spacer"></span>
+        <Button
+          variant={isRequired ? 'primary' : 'ghost'}
+          size="xs"
+          disabled={readonly}
+          aria-pressed={isRequired}
+          aria-label={isRequired ? 'Required (toggle off)' : 'Optional (toggle required)'}
+          onclick={() => toggleRequired(key)}
+        >
+          {isRequired ? 'Required' : 'Optional'}
+        </Button>
+        <Button
+          variant="ghost"
+          size="xs"
+          disabled={readonly}
+          aria-label="Move up"
+          onclick={() => moveProperty(key, -1)}
+        >
+          ↑
+        </Button>
+        <Button
+          variant="ghost"
+          size="xs"
+          disabled={readonly}
+          aria-label="Move down"
+          onclick={() => moveProperty(key, 1)}
+        >
+          ↓
+        </Button>
+        <Button
+          variant="ghost-danger"
+          size="xs"
+          disabled={readonly}
+          aria-label={`Delete ${key}`}
+          onclick={() => deleteProperty(key)}
+        >
+          Delete
+        </Button>
+      </div>
+
+      {#if isOpen}
+        <div id={panelId} class="cinder-jse-property-row__panel">
+          <Input
+            id={`${idPrefix}-${key}-name`}
+            label="Name"
+            value={getDraftName(key)}
+            disabled={readonly}
+            oninput={(event: Event) => (draftNames[key] = (event.target as HTMLInputElement).value)}
+            onblur={() => commitRename(key)}
+          />
+          <PropertyEditor
+            idPrefix={`${idPrefix}-${key}-schema`}
+            path={`${path}/${key}`}
+            depth={depth + 1}
+            {readonly}
+            value={properties[key] ?? {}}
+            onchange={(next) => setPropertySchema(key, next)}
+          />
+        </div>
+      {/if}
+    </div>
+  {/each}
+
+  <Button variant="secondary" size="sm" disabled={readonly} onclick={addProperty}>
+    Add property
+  </Button>
+
+  {#if !readonly || requiredOnly.length > 0}
+    <details class="cinder-jse-required-only" open={requiredOnly.length > 0}>
+      <summary class="cinder-jse-required-only__summary">
+        Required without property schema ({requiredOnly.length})
+      </summary>
+      <div class="cinder-jse-required-only__panel">
+        {#each requiredOnly as name (name)}
+          <Chip
+            mode="removable"
+            label={name}
+            disabled={readonly}
+            onremove={() => removeRequiredOnly(name)}
+          />
+        {/each}
+        <Input
+          id={`${idPrefix}-required-only-add`}
+          label="Add required name"
+          value={newRequiredOnlyName}
+          disabled={readonly}
+          oninput={(event: Event) =>
+            (newRequiredOnlyName = (event.target as HTMLInputElement).value)}
+          onkeydown={(event: KeyboardEvent) => {
+            if (event.key === 'Enter') {
+              event.preventDefault();
+              addRequiredOnly();
+            }
+          }}
+        />
+        <Button variant="secondary" size="sm" disabled={readonly} onclick={addRequiredOnly}>
+          Add required name
+        </Button>
+      </div>
+    </details>
+  {/if}
+</div>

package/src/components/json-viewer/README.md

@@ -0,0 +1,43 @@
+# JsonViewer
+
+Collapsible tree visualization of an arbitrary JSON value with hard depth and byte caps and a fallback for oversized payloads.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import JsonViewer from '@lostgradient/cinder/json-viewer';
+</script>
+
+<JsonViewer value={{ status: 'ok', items: [1, 2, 3] }} />
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop           | Type       | Required | Default | Description                                                                                             |
+| -------------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `class`        | `string`   | no       | —       | Additional class names merged with `.cinder-json-viewer`.                                               |
+| `initialDepth` | `number`   | no       | —       | Initial collapse depth. Nodes deeper than this start collapsed. Default 1.                              |
+| `maxBytes`     | `number`   | no       | —       | Hard byte cap on the serialized payload. Default 1_048_576 (1 MB).                                      |
+| `maxDepth`     | `number`   | no       | —       | Hard depth cap. Nodes deeper than this never render their children. Default 50.                         |
+| `value`        | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact 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 -->

package/src/components/json-viewer/_json-viewer-node.svelte

@@ -0,0 +1,115 @@
+<script lang="ts" module>
+  /**
+   * Internal recursive node for JsonViewer. Not part of the public API;
+   * consumers import JsonViewer directly.
+   */
+  export type JsonViewerNodeProps = {
+    value: unknown;
+    keyName?: string | number;
+    depth: number;
+    initialDepth: number;
+    maxDepth: number;
+  };
+</script>
+
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import Self from './_json-viewer-node.svelte';
+  import { classNames } from '../../utilities/class-names.ts';
+
+  let { value, keyName, depth, initialDepth, maxDepth }: JsonViewerNodeProps = $props();
+
+  const isObject = $derived(value !== null && typeof value === 'object');
+  const isArray = $derived(Array.isArray(value));
+  const tooDeep = $derived(depth >= maxDepth);
+
+  // Seeded once from the initial depth vs. the configured initialDepth.
+  let collapsed = $state(untrack(() => depth >= initialDepth));
+
+  const entries = $derived.by(() => {
+    if (!isObject || tooDeep) return [];
+    if (isArray) {
+      return (value as unknown[]).map((item, i) => [i, item] as const);
+    }
+    return Object.entries(value as Record<string, unknown>);
+  });
+
+  // The key label renders in a sibling <span> outside the <button>, so a screen
+  // reader announces the toggle without any indication of which node it belongs
+  // to. Compose a distinguishing accessible name from the key (when present) and
+  // the collection shape so sibling toggles are tellable apart.
+  const itemCount = $derived(entries.length);
+  const collectionLabel = $derived(
+    `${isArray ? 'array' : 'object'}, ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`,
+  );
+  const toggleLabel = $derived(
+    keyName === undefined ? collectionLabel : `${keyName}: ${collectionLabel}`,
+  );
+
+  function valueClass(v: unknown): string {
+    if (v === null) return 'null';
+    if (typeof v === 'string') return 'string';
+    if (typeof v === 'number') return 'number';
+    if (typeof v === 'boolean') return 'boolean';
+    return 'unknown';
+  }
+</script>
+
+{#if isObject && !tooDeep}
+  <span class={classNames('cinder-json-viewer__node')}>
+    {#if keyName !== undefined}
+      <span class="cinder-json-viewer__key">{keyName}:</span>
+    {/if}
+    <button
+      type="button"
+      class="cinder-json-viewer__toggle"
+      aria-expanded={!collapsed}
+      aria-label={toggleLabel}
+      onclick={() => (collapsed = !collapsed)}
+    >
+      <span class="cinder-json-viewer__caret" data-cinder-collapsed={collapsed || undefined}></span>
+      <span class="cinder-json-viewer__brace">
+        {isArray ? '[' : '{'}
+      </span>
+      {#if collapsed}
+        <span class="cinder-json-viewer__summary"
+          >{itemCount} {itemCount === 1 ? 'item' : 'items'}</span
+        >
+        <span class="cinder-json-viewer__brace">{isArray ? ']' : '}'}</span>
+      {/if}
+    </button>
+    {#if !collapsed}
+      <ul class="cinder-json-viewer__children">
+        <!--
+          For objects `k` is the property name — a stable, correct key. For arrays
+          `k` is the index: JSON array elements carry no intrinsic identity, so if
+          the consumer swaps in a different array each child's collapsed $state
+          stays associated with its position rather than its value. This is an
+          accepted tradeoff given arrays have no stable per-item key.
+        -->
+        {#each entries as [k, v] (k)}
+          <li>
+            <Self value={v} keyName={k} depth={depth + 1} {initialDepth} {maxDepth} />
+          </li>
+        {/each}
+      </ul>
+      <span class="cinder-json-viewer__brace">{isArray ? ']' : '}'}</span>
+    {/if}
+  </span>
+{:else if isObject && tooDeep}
+  <span class="cinder-json-viewer__node">
+    {#if keyName !== undefined}
+      <span class="cinder-json-viewer__key">{keyName}:</span>
+    {/if}
+    <span class="cinder-json-viewer__too-deep">…</span>
+  </span>
+{:else}
+  <span class="cinder-json-viewer__node">
+    {#if keyName !== undefined}
+      <span class="cinder-json-viewer__key">{keyName}:</span>
+    {/if}
+    <span class="cinder-json-viewer__value" data-cinder-type={valueClass(value)}>
+      {#if typeof value === 'string'}"{value}"{:else}{String(value)}{/if}
+    </span>
+  </span>
+{/if}

package/src/components/json-viewer/index.ts

@@ -0,0 +1,6 @@
+import './json-viewer.css';
+import JsonViewer from './json-viewer.svelte';
+
+export default JsonViewer;
+export type { JsonViewerProps } from './json-viewer.types.ts';
+export { JsonViewer };

package/src/components/json-viewer/json-viewer.css

@@ -0,0 +1,115 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  /* ========================================
+ * JSON VIEWER
+ * Collapsible tree visualization. Hard caps live in the component itself.
+ * ======================================== */
+
+  .cinder-json-viewer {
+    font-family: var(--cinder-font-mono);
+    font-size: var(--cinder-text-sm);
+    color: var(--cinder-text);
+    background: var(--cinder-surface-inset);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+    padding: var(--cinder-space-3);
+    overflow: auto;
+  }
+
+  .cinder-json-viewer__fallback {
+    color: var(--cinder-text-muted);
+    font-family: var(--cinder-font-sans);
+    text-align: center;
+    padding: var(--cinder-space-4);
+  }
+
+  .cinder-json-viewer__fallback p {
+    margin: 0 0 var(--cinder-space-1) 0;
+  }
+
+  .cinder-json-viewer__node {
+    display: inline;
+  }
+
+  .cinder-json-viewer__key {
+    color: var(--cinder-accent-text);
+    margin-inline-end: var(--cinder-space-1);
+  }
+
+  .cinder-json-viewer__toggle {
+    appearance: none;
+    background: none;
+    border: none;
+    padding: 0;
+    font: inherit;
+    color: inherit;
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cinder-space-1);
+    border-radius: var(--cinder-radius-sm);
+  }
+
+  .cinder-json-viewer__toggle:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-json-viewer__toggle:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 3px;
+    }
+  }
+
+  .cinder-json-viewer__caret {
+    display: inline-block;
+    width: 0;
+    height: 0;
+    border-inline-start: 0.25rem solid transparent;
+    border-inline-end: 0.25rem solid transparent;
+    border-top: 0.375rem solid currentColor;
+    transition: transform var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  .cinder-json-viewer__caret[data-cinder-collapsed] {
+    transform: rotate(-90deg);
+  }
+
+  .cinder-json-viewer__brace {
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-json-viewer__summary {
+    color: var(--cinder-text-muted);
+    font-style: italic;
+  }
+
+  .cinder-json-viewer__children {
+    list-style: none;
+    margin: 0;
+    padding-inline-start: var(--cinder-space-4);
+    border-inline-start: 1px dashed var(--cinder-border-muted);
+  }
+
+  .cinder-json-viewer__too-deep {
+    color: var(--cinder-text-muted);
+  }
+
+  .cinder-json-viewer__value[data-cinder-type='string'] {
+    color: var(--cinder-success);
+  }
+
+  .cinder-json-viewer__value[data-cinder-type='number'] {
+    color: var(--cinder-warning);
+  }
+
+  .cinder-json-viewer__value[data-cinder-type='boolean'] {
+    color: var(--cinder-danger);
+  }
+
+  .cinder-json-viewer__value[data-cinder-type='null'] {
+    color: var(--cinder-text-muted);
+    font-style: italic;
+  }
+}

package/src/components/json-viewer/json-viewer.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "initialDepth": {
+      "type": "number",
+      "description": "Initial collapse depth. Nodes deeper than this start collapsed. Default 1."
+    },
+    "maxDepth": {
+      "type": "number",
+      "description": "Hard depth cap. Nodes deeper than this never render their children. Default 50."
+    },
+    "maxBytes": {
+      "type": "number",
+      "description": "Hard byte cap on the serialized payload. Default 1_048_576 (1 MB)."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class names merged with `.cinder-json-viewer`."
+    }
+  },
+  "additionalProperties": false,
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "value",
+        "reason": "unknown-shape"
+      }
+    ]
+  }
+}

package/src/components/json-viewer/json-viewer.schema.ts

@@ -0,0 +1,36 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    initialDepth: {
+      type: 'number',
+      description: 'Initial collapse depth. Nodes deeper than this start collapsed. Default 1.',
+    },
+    maxDepth: {
+      type: 'number',
+      description:
+        'Hard depth cap. Nodes deeper than this never render their children. Default 50.',
+    },
+    maxBytes: {
+      type: 'number',
+      description: 'Hard byte cap on the serialized payload. Default 1_048_576 (1 MB).',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-json-viewer`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'value',
+        reason: 'unknown-shape',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;