lumiverse-spindle-types 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/components.ts

@@ -206,6 +206,71 @@ export interface SpindleSwitchHandle extends SpindleMountedComponent<SpindleSwit
 // Pickers & selects
 // ──────────────────────────────────────────────────────────────────────────
 
+/**
+ * Declarative leading-cell content for a select option (avatar, icon, swatch, initial).
+ *
+ * Rendered by the host in the fixed leading slot of both the dropdown row and
+ * the selected-value trigger. Extensions describe what they want declaratively
+ * — they do not pass React nodes themselves.
+ *
+ * Common patterns:
+ * - Persona/character avatars with initial fallback: pick `{ type: "image", src, fallback }`.
+ *   The host shows the image when it loads successfully; if `src` is empty or
+ *   the image fails to load, the host falls back to the supplied initial.
+ * - Provider icons / brand marks: `{ type: "icon-svg" }` or `{ type: "icon-url" }`.
+ * - Color tags / category swatches: `{ type: "swatch", color }`.
+ * - Plain text bubble (initials, single emoji): `{ type: "initial", text }`.
+ */
+export type SpindleSelectOptionLeading =
+  | {
+      type: "image";
+      /** Image URL. Anything `<img src>` accepts, including data URLs. */
+      src: string;
+      /** Alt text for accessibility. Defaults to empty (decorative). */
+      alt?: string;
+      /** Render the image as a circle. Default: `true`. Useful for avatars. */
+      rounded?: boolean;
+      /**
+       * Fallback rendered when `src` is empty or fails to load. Typically a
+       * one-character initial. If omitted, the slot collapses on failure.
+       */
+      fallback?: {
+        /** Fallback text — usually a single character / initial. */
+        text: string;
+        /** Optional background color for the fallback bubble. */
+        background?: string;
+        /** Optional text color for the fallback bubble. */
+        color?: string;
+      };
+    }
+  | {
+      type: "icon-svg";
+      /** Inline SVG string. The host sanitizes and inlines the SVG. */
+      svg: string;
+      /** Optional foreground color applied via `currentColor`. */
+      color?: string;
+    }
+  | {
+      type: "icon-url";
+      /** URL to an icon image (PNG / SVG / WebP). */
+      url: string;
+      alt?: string;
+    }
+  | {
+      type: "swatch";
+      /** Any CSS color string. Rendered as a small filled circle. */
+      color: string;
+    }
+  | {
+      type: "initial";
+      /** Text shown inside the leading bubble — typically one character. */
+      text: string;
+      /** Background color for the bubble. */
+      background?: string;
+      /** Text color inside the bubble. */
+      color?: string;
+    };
+
 /** A single option in a select-style picker. */
 export interface SpindleSelectOption {
   /** Stable value emitted to `onChange`. */
@@ -214,6 +279,13 @@ export interface SpindleSelectOption {
   label: string;
   /** Secondary text rendered beneath the label. */
   sublabel?: string;
+  /**
+   * Optional leading-cell content rendered before the label in both the
+   * dropdown row and the selected-value trigger. See {@link SpindleSelectOptionLeading}
+   * for the supported variants (avatar image with initial fallback, inline
+   * SVG icon, icon URL, color swatch, plain initial bubble).
+   */
+  leading?: SpindleSelectOptionLeading;
   /** Group key. Options sharing a group are visually clustered with a header. */
   group?: string;
   /** Render as disabled. */

package/src/index.ts

@@ -232,6 +232,7 @@ export type {
   SpindleSwitchOptions,
   SpindleSwitchHandle,
   SpindleSelectOption,
+  SpindleSelectOptionLeading,
   SpindleSelectOptionsBase,
   SpindleSelectOptions,
   SpindleSelectHandle,