@inglorious/ui 0.1.0 → 1.0.0

package/src/data-display/icon/icon-implementations.mdx

@@ -0,0 +1,160 @@
+import { Meta } from "@storybook/addon-docs/blocks"
+
+<Meta title="Data Display/Icon/Implementations" />
+
+<div className="iw-theme-content">
+
+# Icon Implementations
+
+Use this page as a quick reference for supported icon strategies in `@inglorious/ui`.
+
+<style>{`
+  .iw-icon-tabs { display: grid; gap: 0.75rem; }
+  .iw-icon-tabs > input { position: absolute; opacity: 0; pointer-events: none; }
+  .iw-icon-tab-labels { display: flex; flex-wrap: wrap; gap: 0.5rem; }
+  .iw-icon-tab-labels label {
+    border: 1px solid var(--iw-color-border);
+    border-radius: var(--iw-radius-md);
+    background: var(--iw-color-bg-secondary);
+    color: var(--iw-color-text);
+    padding: 0.35rem 0.65rem;
+    cursor: pointer;
+    font-size: 0.875rem;
+  }
+  .iw-icon-tab-panels {
+    border: 1px solid var(--iw-color-border);
+    border-radius: var(--iw-radius-md);
+    background: var(--iw-color-surface);
+    padding: 0.85rem;
+  }
+  .iw-icon-tab-panel { display: none; line-height: 1.45; }
+  #iw-icon-tab-generic:checked ~ .iw-icon-tab-panels .iw-icon-tab-panel-generic,
+  #iw-icon-tab-svg:checked ~ .iw-icon-tab-panels .iw-icon-tab-panel-svg,
+  #iw-icon-tab-material:checked ~ .iw-icon-tab-panels .iw-icon-tab-panel-material,
+  #iw-icon-tab-fa:checked ~ .iw-icon-tab-panels .iw-icon-tab-panel-fa,
+  #iw-icon-tab-lucide:checked ~ .iw-icon-tab-panels .iw-icon-tab-panel-lucide,
+  #iw-icon-tab-a11y:checked ~ .iw-icon-tab-panels .iw-icon-tab-panel-a11y { display: block; }
+  #iw-icon-tab-generic:checked ~ .iw-icon-tab-labels label[for="iw-icon-tab-generic"],
+  #iw-icon-tab-svg:checked ~ .iw-icon-tab-labels label[for="iw-icon-tab-svg"],
+  #iw-icon-tab-material:checked ~ .iw-icon-tab-labels label[for="iw-icon-tab-material"],
+  #iw-icon-tab-fa:checked ~ .iw-icon-tab-labels label[for="iw-icon-tab-fa"],
+  #iw-icon-tab-lucide:checked ~ .iw-icon-tab-labels label[for="iw-icon-tab-lucide"],
+  #iw-icon-tab-a11y:checked ~ .iw-icon-tab-labels label[for="iw-icon-tab-a11y"] {
+    border-color: var(--iw-color-primary);
+    box-shadow: inset 0 0 0 1px var(--iw-color-primary);
+  }
+  .iw-icon-example { display: inline-flex; align-items: center; gap: 0.5rem; font-size: 1.5rem; margin-top: 0.35rem; }
+  .iw-material-symbol {
+    font-family: "Material Symbols Outlined";
+    font-weight: 400;
+    font-style: normal;
+    font-size: 1.5rem;
+    line-height: 1;
+    letter-spacing: normal;
+    text-transform: none;
+    display: inline-block;
+    white-space: nowrap;
+    word-wrap: normal;
+    direction: ltr;
+    font-feature-settings: "liga";
+    -webkit-font-smoothing: antialiased;
+  }
+  .iw-theme-content { background: var(--iw-color-bg, #ffffff); color: var(--iw-color-text, #000000); padding: 1rem; border-radius: var(--iw-radius-md); }
+  .iw-theme-content h1, .iw-theme-content p, .iw-theme-content li, .iw-theme-content pre, .iw-theme-content code { background: var(--iw-color-surface, #ffffff); color: var(--iw-color-text, #000000); }
+`}</style>
+
+<div className="iw-icon-tabs">
+  <input id="iw-icon-tab-generic" type="radio" name="iw-icon-tab" defaultChecked />
+  <input id="iw-icon-tab-svg" type="radio" name="iw-icon-tab" />
+  <input id="iw-icon-tab-material" type="radio" name="iw-icon-tab" />
+  <input id="iw-icon-tab-fa" type="radio" name="iw-icon-tab" />
+  <input id="iw-icon-tab-lucide" type="radio" name="iw-icon-tab" />
+  <input id="iw-icon-tab-a11y" type="radio" name="iw-icon-tab" />
+
+  <div className="iw-icon-tab-labels">
+    <label htmlFor="iw-icon-tab-generic">Generic</label>
+    <label htmlFor="iw-icon-tab-svg">Inline SVG</label>
+    <label htmlFor="iw-icon-tab-material">Material</label>
+    <label htmlFor="iw-icon-tab-fa">Font Awesome</label>
+    <label htmlFor="iw-icon-tab-lucide">Lucide</label>
+    <label htmlFor="iw-icon-tab-a11y">Accessibility</label>
+  </div>
+
+  <div className="iw-icon-tab-panels">
+    <section className="iw-icon-tab-panel iw-icon-tab-panel-generic">
+      <p>Use <code>@inglorious/ui/icon</code> for glyphs, emoji, and simple symbols. Reference: <a href="/?path=/story/data-display-icon--unicode">UTF-8 Icons</a></p>
+      <pre><code>{`icon.render({ children: "★", size: "md", color: "primary" })`}</code></pre>
+      <div className="iw-icon-example">★ ⚑ ♫</div>
+    </section>
+
+    <section className="iw-icon-tab-panel iw-icon-tab-panel-svg">
+      <p>Use inline SVG when you want a custom icon pack without font dependencies.</p>
+      <pre><code>{`icon.render({
+    children: html\`<svg viewBox="0 0 24 24" ...>...</svg>\`,
+    size: "md",
+})`}</code></pre>
+
+<div className="iw-icon-example">
+<svg width="22" height="22" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+<path d="M12 2v20M2 12h20" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+</svg>
+<svg width="22" height="22" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+<path d="M3 12l6 6 12-12" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+</svg>
+<svg width="22" height="22" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+<path d="M12 21s-7-4.35-9-8.5C1.25 8.6 3.8 5 7.6 5c2.1 0 3.4 1.1 4.4 2.5C13 6.1 14.3 5 16.4 5 20.2 5 22.75 8.6 21 12.5 19 16.65 12 21 12 21Z" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+</svg>
+</div>
+</section>
+
+    <section className="iw-icon-tab-panel iw-icon-tab-panel-material">
+      <p>Use <code>@inglorious/ui/material-icon</code> when Material Symbols fonts are loaded. Reference: <a href="https://fonts.google.com/icons?icon.set=Material+Icons" target="_blank">Material Icons</a></p>
+      <pre><code>{`materialIcon.render({ name: "home", filled: true, size: "md" })`}</code></pre>
+      <div className="iw-icon-example">
+        <span className="iw-material-symbol" aria-hidden="true">home</span>
+        <span className="iw-material-symbol" aria-hidden="true">settings</span>
+        <span className="iw-material-symbol" aria-hidden="true">favorite</span>
+      </div>
+    </section>
+
+    <section className="iw-icon-tab-panel iw-icon-tab-panel-fa">
+      <p>Load Font Awesome CSS globally, then pass an icon element as <code>children</code>. Reference: <a href="https://fontawesome.com/search" target="_blank">Font Awesome Icons</a></p>
+      <pre><code>{`icon.render({
+    children: html\`<i class="fa-solid fa-user" aria-hidden="true"></i>\`,
+})`}</code></pre>
+
+<div className="iw-icon-example">
+<i className="fa-solid fa-user" aria-hidden="true"></i>
+<i className="fa-solid fa-gear" aria-hidden="true"></i>
+<i className="fa-solid fa-heart" aria-hidden="true"></i>
+</div>
+</section>
+
+    <section className="iw-icon-tab-panel iw-icon-tab-panel-lucide">
+      <p>Lucide requires runtime bootstrapping before icons render. Reference: <a href="https://lucide.dev/icons/?focus" target="_blank">Lucide Icons</a></p>
+      <pre><code>{`import { createIcons, icons } from "lucide"
+createIcons({
+    icons,
+    attrs: { "stroke-width": 1.75 },
+})`}</code></pre>
+      <p>Then render nodes such as <code>{`<i data-lucide="user"></i>`}</code>.</p>
+
+<div className="iw-icon-example">
+<i data-lucide="user" aria-hidden="true"></i>
+<i data-lucide="settings" aria-hidden="true"></i>
+<i data-lucide="heart" aria-hidden="true"></i>
+</div>
+</section>
+
+    <section className="iw-icon-tab-panel iw-icon-tab-panel-a11y">
+      <ul>
+        <li>Decorative icons: use <code>aria-hidden="true"</code>.</li>
+        <li>Meaningful icons: include an <code>aria-label</code> or visible text.</li>
+        <li>Do not rely on icon shape alone for state; pair with text/color contrast.</li>
+      </ul>
+      <p>Unicode glyph explorer lives in the <strong>Data Display/Icon/Unicode</strong> story.</p>
+    </section>
+
+</div>
+</div>
+</div>

package/src/data-display/icon/icon-utf8.stories.js

@@ -0,0 +1,156 @@
+import { virtualList } from "@inglorious/ui/virtual-list"
+import { html, repeat } from "@inglorious/web"
+
+import { button } from "../../controls/button"
+import {
+  createEntityRender,
+  notifyActionArgType,
+} from "../../stories/notifyStory.js"
+import { icon } from "."
+
+const unicodeList = {
+  ...virtualList,
+
+  create(entity) {
+    virtualList.create(entity)
+
+    const items = []
+    let rowIndex = 0
+    let row = []
+
+    for (let code = entity.start; code <= entity.end; code += 1) {
+      row.push(code)
+      if (row.length >= entity.columns) {
+        items.push({ id: `row-${rowIndex}`, codes: row })
+        row = []
+        rowIndex += 1
+      }
+    }
+
+    if (row.length) {
+      items.push({ id: `row-${rowIndex}`, codes: row })
+    }
+
+    entity.items = items
+  },
+
+  render(entity, api) {
+    return virtualList.render(entity, {
+      ...api,
+      getType: () => unicodeList,
+    })
+  },
+
+  renderItem(entity, { item }) {
+    const { columns = 16, size = "md" } = entity
+    const codes = item.codes ?? []
+
+    return html`
+      <div
+        style=${[
+          "display: grid",
+          `grid-template-columns: repeat(${columns}, minmax(0, 1fr))`,
+          "gap: 0.5rem",
+          "align-items: center",
+        ].join("; ")}
+      >
+        ${repeat(
+          codes,
+          (code) => code,
+          (code) => {
+            const glyph = String.fromCodePoint(code)
+            const label = `Copy U+${code
+              .toString(16)
+              .toUpperCase()
+              .padStart(4, "0")}`
+
+            return button.render({
+              id: code,
+              variant: "ghost",
+              color: "default",
+              size: "sm",
+              shape: "square",
+              ariaLabel: label,
+              onClick: () => copyGlyph(glyph),
+              children: icon.render({
+                children: glyph,
+                size,
+                color: "current",
+              }),
+            })
+          },
+        )}
+      </div>
+    `
+  },
+}
+
+export default {
+  title: "Data Display/Icon",
+  render: createEntityRender({ unicodeList }),
+  argTypes: {
+    ...notifyActionArgType,
+    start: {
+      control: "number",
+      description: "Start code point (decimal).",
+    },
+    end: {
+      control: "number",
+      description: "End code point (decimal).",
+    },
+    columns: {
+      control: "number",
+      description: "Grid columns for the glyphs.",
+    },
+    viewportHeight: {
+      control: "number",
+      description: "Viewport height for the virtualized list (px).",
+    },
+    estimatedHeight: {
+      control: "number",
+      description: "Estimated row height for virtualization (px).",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Unicode glyph explorer for the icon primitive. Click a glyph to copy it.",
+      },
+    },
+  },
+}
+
+export const Unicode = {
+  args: {
+    id: "unicodeList",
+    type: "unicodeList",
+    start: 0,
+    end: 129799,
+    columns: 20,
+    viewportHeight: 600,
+    estimatedHeight: 56,
+    size: "lg",
+  },
+}
+
+async function copyGlyph(glyph) {
+  if (navigator?.clipboard?.writeText) {
+    await navigator.clipboard.writeText(glyph)
+    return
+  }
+
+  const textarea = document.createElement("textarea")
+  textarea.value = glyph
+  textarea.setAttribute("readonly", "")
+  textarea.style.position = "absolute"
+  textarea.style.left = "-9999px"
+  document.body.appendChild(textarea)
+  textarea.select()
+  document.execCommand("copy")
+  document.body.removeChild(textarea)
+}

package/src/data-display/icon/icon.stories.js

@@ -0,0 +1,38 @@
+import { createRender } from "../../stories/notifyStory.js"
+import { icon } from "."
+
+export default {
+  title: "Data Display/Icon",
+  tags: ["autodocs"],
+  render: createRender(icon),
+  argTypes: {
+    children: { control: "text", description: "Icon glyph or inline content." },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+      description: "Icon size scale.",
+    },
+    color: {
+      control: "text",
+      description:
+        "Any valid CSS color value (`current` keeps inherited color).",
+    },
+    onClick: { action: "onClick" },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Generic inline icon primitive for glyphs, emoji, or custom symbol text. See `Data Display/Icon/Implementations` for Font Awesome and Lucide setup patterns.",
+      },
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    children: "★",
+    size: "md",
+    color: "current",
+  },
+}

package/src/data-display/icon/index.js

@@ -0,0 +1,3 @@
+import * as renderers from "./template.js"
+
+export const icon = { ...renderers }

package/src/data-display/icon/style.css

@@ -0,0 +1,17 @@
+.iw-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1em;
+  height: 1em;
+  line-height: 1;
+  cursor: pointer;
+
+  &.iw-icon-sm {
+    font-size: 0.875rem;
+  }
+
+  &.iw-icon-lg {
+    font-size: 1.5rem;
+  }
+}

package/src/data-display/icon/template.js

@@ -0,0 +1,19 @@
+/**
+ * @typedef {import('../../../types/data-display/icon').IconProps} IconProps
+ */
+
+import { classMap, html } from "@inglorious/web"
+
+export function render({ children, size = "md", color = "current", onClick }) {
+  return html`<span
+    class=${classMap({
+      "iw-icon": true,
+      [`iw-icon-${size}`]: size !== "md",
+      "iw-icon-current": color === "current",
+    })}
+    style=${color !== "current" ? `color: ${color};` : ""}
+    aria-hidden="true"
+    @click=${onClick}
+    >${children}</span
+  >`
+}

package/src/data-display/list/handlers.js

@@ -0,0 +1,25 @@
+export function itemToggle(entity, payload) {
+  if (!payload?.path?.length) return
+
+  entity.items = toggleItemByPath(entity.items, payload.path)
+}
+
+function toggleItemByPath(items, path) {
+  if (!Array.isArray(items) || path.length === 0) return items
+
+  const [index, ...rest] = path
+  return items.map((item, itemIndex) => {
+    if (itemIndex !== index || !item || typeof item !== "object") return item
+
+    if (rest.length === 0) {
+      const isExpanded = !!item.isExpanded
+      return { ...item, isExpanded: !isExpanded }
+    }
+
+    const children = Array.isArray(item.children)
+      ? toggleItemByPath(item.children, rest)
+      : item.children
+
+    return { ...item, children }
+  })
+}

package/src/data-display/list/index.js

@@ -0,0 +1,4 @@
+import * as handlers from "./handlers.js"
+import { list as renderers } from "./template.js"
+
+export const list = { ...renderers, ...handlers }

package/src/data-display/list/list.stories.js

@@ -0,0 +1,187 @@
+import { createRender } from "../../stories/notifyStory.js"
+import { list } from "."
+
+export default {
+  title: "Data Display/List",
+  tags: ["autodocs"],
+  render: createRender(list),
+  argTypes: {
+    items: {
+      control: "object",
+      description: "Items rendered by default renderer.",
+    },
+    isOrdered: {
+      control: "boolean",
+      description: "Use ordered list semantics.",
+    },
+    isDense: {
+      control: "boolean",
+      description: "Reduce item vertical spacing.",
+    },
+    isDivided: {
+      control: "boolean",
+      description: "Add separators between items.",
+    },
+    isInset: {
+      control: "boolean",
+      description: "Align items without icons to those with icons.",
+    },
+    padding: {
+      control: "select",
+      options: ["none", "sm", "md", "lg", "xl"],
+      description: "Outer padding for the list.",
+    },
+    onItemClick: { action: "onItemClick" },
+    onItemToggle: { action: "onItemToggle" },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "List primitive with optional ordered mode and overridable `renderItem(props, payload)` sub-render. Click events use `onItemClick(item, path)` and toggle events use `onItemToggle(item, path)`.",
+      },
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    items: [
+      { id: "a", primary: "First item", secondary: "Secondary text" },
+      { id: "b", primary: "Second item", secondary: "More details" },
+      { id: "c", primary: "Third item", secondary: "Optional caption" },
+    ],
+    isOrdered: false,
+    isDense: false,
+    isDivided: false,
+    padding: "none",
+  },
+}
+
+export const Ordered = {
+  args: {
+    ...Default.args,
+    isOrdered: true,
+  },
+}
+
+export const Dense = {
+  args: {
+    ...Default.args,
+    isDense: true,
+  },
+}
+
+export const Divided = {
+  args: {
+    ...Default.args,
+    isDivided: true,
+  },
+}
+
+export const WithIcons = {
+  args: {
+    items: [
+      { id: "a", icon: "★", primary: "Starred", secondary: "Pinned item" },
+      { id: "b", primary: "Settings", secondary: "Manage options" },
+      { id: "c", icon: "✓", primary: "Done", secondary: "Completed task" },
+    ],
+    isOrdered: false,
+    isDense: false,
+    isDivided: true,
+    isInset: true,
+  },
+}
+
+export const Selected = {
+  args: {
+    items: [
+      { id: "a", primary: "Inbox", isSelected: true },
+      { id: "b", primary: "Drafts" },
+      { id: "c", primary: "Archive" },
+    ],
+  },
+}
+
+export const Disabled = {
+  args: {
+    items: [
+      { id: "a", primary: "Active item" },
+      { id: "b", primary: "Disabled item", isDisabled: true },
+    ],
+  },
+}
+
+export const Nested = {
+  args: {
+    items: [
+      {
+        id: "a",
+        primary: "Parent item",
+        isExpanded: true,
+        children: [
+          { id: "a-1", primary: "Child item 1" },
+          { id: "a-2", primary: "Child item 2", isSelected: true },
+        ],
+      },
+      { id: "b", primary: "Sibling item" },
+    ],
+    isDivided: true,
+  },
+}
+
+export const NestedWithIcons = {
+  args: {
+    items: [
+      {
+        id: "a",
+        icon: "📁",
+        primary: "Projects",
+        isExpanded: true,
+        children: [
+          { id: "a-1", icon: "📄", primary: "Spec.md" },
+          { id: "a-2", primary: "Notes", isSelected: true },
+        ],
+      },
+      { id: "b", icon: "🗂️", primary: "Archive" },
+    ],
+    isDivided: true,
+    isInset: true,
+  },
+}
+
+export const WithActions = {
+  args: {
+    items: [
+      {
+        id: "a",
+        primary: "Notifications",
+        secondary: "Enable alerts",
+        action: "On",
+      },
+      {
+        id: "b",
+        primary: "Wi-Fi",
+        secondary: "Office network",
+        action: "⋯",
+      },
+    ],
+  },
+}
+
+export const Expandable = {
+  args: {
+    items: [
+      {
+        id: "a",
+        primary: "Inbox",
+        isExpanded: false,
+        children: [
+          { id: "a-1", primary: "Starred" },
+          { id: "a-2", primary: "Drafts" },
+        ],
+      },
+      { id: "b", primary: "Archive" },
+    ],
+  },
+}