luxen-ui 0.1.0

package/dist/skills/luxen-ui/references/tree.md

@@ -0,0 +1,359 @@
+---
+outline: deep
+---
+
+# Tree
+
+Tree views present hierarchical data like file explorers, navigation menus, and taxonomies. Each node expands/collapses to reveal nested items and can be selected in several ways.
+
+<ElementSpec
+  tag="l-tree"
+  type="shadow"
+/>
+
+## Options
+
+### Basic
+
+Wrap `<l-tree-item>` nodes inside `<l-tree>`. Nested `<l-tree-item>` children become sub-nodes automatically.
+
+<ComponentWrapper vertical :html="treeBasic" />
+
+```html
+<l-tree>
+  <l-tree-item>
+    Documents
+    <l-tree-item>
+      Photos
+      <l-tree-item>beach.jpg</l-tree-item>
+      <l-tree-item>mountain.jpg</l-tree-item>
+    </l-tree-item>
+    <l-tree-item>
+      Invoices
+      <l-tree-item>january.pdf</l-tree-item>
+      <l-tree-item>february.pdf</l-tree-item>
+    </l-tree-item>
+  </l-tree-item>
+  <l-tree-item>
+    Projects
+    <l-tree-item>luxen-ui</l-tree-item>
+    <l-tree-item>website</l-tree-item>
+  </l-tree-item>
+  <l-tree-item>Downloads</l-tree-item>
+</l-tree>
+```
+
+### Custom icons
+
+Place any element in the `prefix` slot to render a leading icon before the label. Icons inherit the current text color.
+
+<ComponentWrapper vertical :html="treeIcons" />
+
+```html
+<l-tree>
+  <l-tree-item expanded>
+    <l-icon
+      slot="prefix"
+      name="lucide:folder-open"
+    ></l-icon>
+    src
+    <l-tree-item>
+      <l-icon
+        slot="prefix"
+        name="lucide:folder"
+      ></l-icon>
+      components
+      <l-tree-item>
+        <l-icon
+          slot="prefix"
+          name="lucide:file-code"
+        ></l-icon>
+        Button.ts
+      </l-tree-item>
+      <l-tree-item>
+        <l-icon
+          slot="prefix"
+          name="lucide:file-code"
+        ></l-icon>
+        Tree.ts
+      </l-tree-item>
+    </l-tree-item>
+    <l-tree-item>
+      <l-icon
+        slot="prefix"
+        name="lucide:file-json"
+      ></l-icon>
+      package.json
+    </l-tree-item>
+    <l-tree-item>
+      <l-icon
+        slot="prefix"
+        name="lucide:file-text"
+      ></l-icon>
+      README.md
+    </l-tree-item>
+  </l-tree-item>
+  <l-tree-item>
+    <l-icon
+      slot="prefix"
+      name="lucide:folder"
+    ></l-icon>
+    public
+    <l-tree-item>
+      <l-icon
+        slot="prefix"
+        name="lucide:image"
+      ></l-icon>
+      logo.svg
+    </l-tree-item>
+  </l-tree-item>
+</l-tree>
+```
+
+### Custom expand icons
+
+Override the `expand-icon` and `collapse-icon` slots to show a different icon per state — e.g. a closed folder when the branch is collapsed and an open folder when expanded. Leaves keep the `prefix` slot for their own icon.
+
+<ComponentWrapper vertical :html="treeExpandIcons" />
+
+```html
+<l-tree>
+  <l-tree-item expanded>
+    <l-icon
+      slot="expand-icon"
+      name="lucide:folder"
+    ></l-icon>
+    <l-icon
+      slot="collapse-icon"
+      name="lucide:folder-open"
+    ></l-icon>
+    src
+    <l-tree-item>
+      <l-icon
+        slot="expand-icon"
+        name="lucide:folder"
+      ></l-icon>
+      <l-icon
+        slot="collapse-icon"
+        name="lucide:folder-open"
+      ></l-icon>
+      components
+      <l-tree-item>
+        <l-icon
+          slot="prefix"
+          name="lucide:file-code"
+        ></l-icon>
+        Button.ts
+      </l-tree-item>
+      <l-tree-item>
+        <l-icon
+          slot="prefix"
+          name="lucide:file-code"
+        ></l-icon>
+        Tree.ts
+      </l-tree-item>
+    </l-tree-item>
+    <l-tree-item>
+      <l-icon
+        slot="prefix"
+        name="lucide:file-json"
+      ></l-icon>
+      package.json
+    </l-tree-item>
+    <l-tree-item>
+      <l-icon
+        slot="prefix"
+        name="lucide:file-text"
+      ></l-icon>
+      README.md
+    </l-tree-item>
+  </l-tree-item>
+</l-tree>
+```
+
+### Row actions
+
+Place any interactive element inside a `<l-tree-item>` to expose per-row actions (e.g. an `<l-dropdown>` menu, a button, a link). Clicks on `<button>`, `<a>`, `<input>` and elements with `role="button"` or `role="menuitem"` never toggle the row's selection or expansion.
+
+This demo is controlled from Vue state: the yellow `…` trigger is rendered only on the selected row via `v-if`, so clicking another row moves the button there without duplicating it in the DOM.
+
+<TreeActionsDemo />
+
+### Multiple selection
+
+Set `selection="multiple"` to render a native checkbox on every item. Toggling a parent cascades the selection to its descendants and sets the indeterminate state when only some children are selected.
+
+<ComponentWrapper vertical :html="treeMultiple" />
+
+```html
+<l-tree selection="multiple">
+  <l-tree-item expanded>
+    Fruits
+    <l-tree-item>Apple</l-tree-item>
+    <l-tree-item selected>Banana</l-tree-item>
+    <l-tree-item>Cherry</l-tree-item>
+  </l-tree-item>
+  <l-tree-item>
+    Vegetables
+    <l-tree-item>Carrot</l-tree-item>
+    <l-tree-item>Lettuce</l-tree-item>
+  </l-tree-item>
+</l-tree>
+```
+
+### Independent selection
+
+Add `independent` to decouple parents and children: a parent can be selected without ticking any of its descendants and vice-versa. Useful when nodes represent independent concepts (categories, tags, permissions) rather than aggregations.
+
+<ComponentWrapper vertical :html="treeIndependent" />
+
+```html
+<l-tree
+  selection="multiple"
+  independent
+>
+  <l-tree-item expanded>
+    Region: Europe
+    <l-tree-item>France</l-tree-item>
+    <l-tree-item>Germany</l-tree-item>
+    <l-tree-item>Italy</l-tree-item>
+  </l-tree-item>
+  <l-tree-item expanded>
+    Region: Americas
+    <l-tree-item>Brazil</l-tree-item>
+    <l-tree-item>United States</l-tree-item>
+  </l-tree-item>
+</l-tree>
+```
+
+### Leaf-only selection
+
+Set `selection="leaf"` when only terminal nodes represent selectable values. Clicking a branch only toggles its expansion.
+
+<ComponentWrapper vertical :html="treeLeaf" />
+
+```html
+<l-tree selection="leaf">
+  <l-tree-item expanded>
+    Components
+    <l-tree-item>Button</l-tree-item>
+    <l-tree-item>Dropdown</l-tree-item>
+    <l-tree-item>Tree</l-tree-item>
+  </l-tree-item>
+  <l-tree-item>
+    Tokens
+    <l-tree-item>Colors</l-tree-item>
+    <l-tree-item>Spacing</l-tree-item>
+  </l-tree-item>
+</l-tree>
+```
+
+### Disabled items
+
+Add `disabled` to any item to prevent selection and interaction. The item remains visible and part of the structure.
+
+<ComponentWrapper vertical :html="treeDisabled" />
+
+```html
+<l-tree selection="multiple">
+  <l-tree-item expanded>
+    Settings
+    <l-tree-item>Profile</l-tree-item>
+    <l-tree-item disabled>Billing (locked)</l-tree-item>
+    <l-tree-item>Notifications</l-tree-item>
+  </l-tree-item>
+</l-tree>
+```
+
+### Lazy loading
+
+Add `lazy` to an item whose children will be fetched on first expand. The component emits `lazy-load`; set `loading` to render a spinner in place of the chevron, then append children and remove `lazy`.
+
+<TreeLazyDemo />
+
+## Examples
+
+### Comment thread
+
+A discussion tree styled like a Reddit comment thread. Demonstrates stacking `prefix` (avatar), the default slot (multi-line content + action buttons), and swapped `expand-icon` / `collapse-icon` slots (`lucide:circle-plus` / `lucide:circle-minus`). The `::part(base)` and `::part(label)` are overridden to align content to the top and allow wrapping; `--indent-size` and `--indent-guide-width` are tuned for the denser look.
+
+<TreeRedditDemo />
+
+## Accessibility
+
+### Criteria
+
+| Check | Description |
+|-------|-------------|
+| Role | Container has `role="tree"`, items have `role="treeitem"`, groups have `role="group"` |
+| Expanded state | Branches expose `aria-expanded` reflecting open state. Leaf nodes omit the attribute. |
+| Selected state | Selected items expose `aria-selected="true"` |
+| Multi-selectable | Container sets `aria-multiselectable="true"` when `selection="multiple"` |
+| Disabled state | Disabled items expose `aria-disabled="true"` and stay in the DOM for discoverability |
+| Focus management | Roving tabindex: only one item is in the tab order at a time; arrow keys move focus within the tree |
+| Motion | Chevron rotation and spinner respect `prefers-reduced-motion` |
+
+### Rules
+- Every item needs visible text content for its accessible name
+- Use `selection="leaf"` when branches are never valid values — this prevents keyboard users from accidentally selecting aggregations
+- Prefer `selection="multiple" independent` for forms where parent selection is a distinct choice from the children
+
+### Keyboard interactions
+
+| Key | Description |
+|-----|-------------|
+| ArrowDown | Moves focus to the next visible item |
+| ArrowUp | Moves focus to the previous visible item |
+| ArrowRight | Expands a collapsed branch, or moves to the first child when already expanded |
+| ArrowLeft | Collapses an expanded branch, or moves to the parent item |
+| Home | Moves focus to the first visible item |
+| End | Moves focus to the last visible item |
+| Enter | Activates the item (selects or toggles expansion depending on mode) |
+| Space | Activates the item (selects or toggles expansion depending on mode) |
+| * | Expands all sibling branches of the focused item |
+
+## API reference
+
+### Importing
+
+```js
+import 'luxen-ui/tree';
+import 'luxen-ui/tree-item';
+```
+
+### Attributes & Properties
+
+<ApiTable :data="[
+  { Attribute: 'selection', Description: 'Selection mode: `single` (default), `multiple`, `leaf`, or `none`' },
+  { Attribute: 'independent', Description: 'When set with `selection=&quot;multiple&quot;`, parent and descendants selection are decoupled (no cascade, no indeterminate)' },
+]" />
+
+### Methods
+
+<ApiTable :data="[
+  { Method: 'getAllItems()', Description: 'Returns every `<l-tree-item>` in document order (including nested)' },
+  { Method: 'getSelection()', Description: 'Returns the currently selected items' },
+  { Method: 'expandAll()', Description: 'Expands every branch' },
+  { Method: 'collapseAll()', Description: 'Collapses every item' },
+]" />
+
+### Events
+
+<ApiTable :data="[
+  { Event: 'selection-change', Description: 'Fired when the selection changes. Detail: `{ selection }`' },
+]" />
+
+### CSS custom properties
+
+<ApiTable :data="[
+  { Name: '--indent-size', Description: 'Horizontal indent per depth level. Default `1rem`' },
+  { Name: '--indent-guide-width', Description: 'Thickness of the vertical guide line between a parent and its children. Default `1px`. Set to `0` to hide guides' },
+  { Name: '--indent-guide-style', Description: 'Line style of the guide: `solid` (default), `dashed`, `dotted`, `double`' },
+  { Name: '--indent-guide-color', Description: 'Color of the guide line' },
+  { Name: '--row-height', Description: 'Minimum row height. Default `1.75rem`' },
+  { Name: '--row-padding-inline', Description: 'Inner inline padding of the row; also drives the content slot left indent and the guide column. Default `0.25rem`' },
+  { Name: '--chevron-size', Description: 'Size of the expand/collapse chevron/avatar box. Default `1.125rem`' },
+  { Name: '--item-gap', Description: 'Horizontal gap between chevron, prefix, label and suffix on the row; also drives the content slot left indent. Default `0.375rem`' },
+]" />
+
+See [`<l-tree-item>`](/elements/tree-item) for the per-item API.

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "luxen-ui",
+  "version": "0.1.0",
+  "description": "Modern web components and CSS-first UI library built with Lit. Framework-agnostic, customizable prefix, design tokens.",
+  "keywords": [
+    "custom-elements",
+    "design-system",
+    "lit",
+    "ui-library",
+    "web-components"
+  ],
+  "homepage": "https://luxen-ui.com",
+  "bugs": {
+    "url": "https://github.com/luxen-ui/luxen-ui/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Luxen UI",
+    "url": "https://luxen-ui.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luxen-ui/luxen-ui.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "dist/",
+    "vite-plugin.ts",
+    "postcss-plugin-prefix.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css",
+    "**/define.js",
+    "**/registry.js"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./css": {
+      "style": "./dist/css/index.css",
+      "import": "./dist/css/index.css"
+    },
+    "./css/base": {
+      "style": "./dist/css/index.css",
+      "import": "./dist/css/index.css"
+    },
+    "./css/*": {
+      "style": "./dist/css/elements/*.css",
+      "import": "./dist/css/elements/*.css"
+    },
+    "./dist/custom-elements.json": "./dist/custom-elements.json",
+    "./dist/elements/*": "./dist/elements/*",
+    "./dist/css/*": "./dist/css/*",
+    "./vite-plugin": "./vite-plugin.ts",
+    "./postcss-plugin-prefix": "./postcss-plugin-prefix.js",
+    "./*/element": {
+      "types": "./dist/elements/*/*.d.ts",
+      "import": "./dist/elements/*/*.js"
+    },
+    "./luxen-element": {
+      "types": "./dist/shared/luxen-element.d.ts",
+      "import": "./dist/shared/luxen-element.js"
+    },
+    "./luxen-form-associated-element": {
+      "types": "./dist/shared/luxen-form-associated-element.d.ts",
+      "import": "./dist/shared/luxen-form-associated-element.js"
+    },
+    "./*": {
+      "types": "./dist/elements/*/index.d.ts",
+      "import": "./dist/elements/*/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "scripts": {
+    "dev": "WATCH=true DEV=true vp build --config vite.config.css.ts",
+    "dev:elements": "vp dev",
+    "build": "vp build --config vite.config.css.ts && tsc && node scripts/copy-styles.mjs && vp build && pnpm run manifest && node scripts/generate-skill.mjs",
+    "build:css": "vp build --config vite.config.css.ts",
+    "build:skill": "node scripts/generate-skill.mjs",
+    "manifest": "cem analyze --litelement --outdir dist",
+    "preview": "vp preview"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "catalog:",
+    "embla-carousel": "catalog:",
+    "embla-carousel-autoplay": "catalog:",
+    "iconify-icon": "catalog:",
+    "lit": "catalog:"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "catalog:",
+    "@custom-elements-manifest/to-markdown": "catalog:",
+    "@types/node": "catalog:",
+    "autoprefixer": "catalog:",
+    "css-extras": "catalog:",
+    "postcss": "catalog:",
+    "postcss-import": "catalog:",
+    "tinyglobby": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plugin-dts": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "customElements": "dist/custom-elements.json"
+}

package/postcss-plugin-prefix.js

@@ -0,0 +1,63 @@
+/**
+ * PostCSS plugin that rewrites all `l-` prefixed identifiers in CSS.
+ *
+ * Runs after `postcss-import` inlines all `@import`s, so imported files
+ * like `_tokens.css` are also rewritten.
+ *
+ * Supports separate element and CSS prefixes:
+ * - Element prefix: type selectors (`l-toast` → `{elementPrefix}-toast`)
+ * - CSS prefix: classes, custom properties, keyframes, animation references
+ *
+ * @param {{ elementPrefix?: string, cssPrefix?: string }} opts
+ */
+const plugin = (opts = {}) => {
+  const elementPrefix = opts.elementPrefix || 'l';
+  const cssPrefix = opts.cssPrefix || 'l';
+  if (elementPrefix === 'l' && cssPrefix === 'l') return { postcssPlugin: 'luxen-prefix' };
+
+  return {
+    postcssPlugin: 'luxen-prefix',
+
+    Once(root) {
+      root.walk((node) => {
+        if (node.type === 'atrule') {
+          if (node.name === 'keyframes' && node.params.startsWith('l-')) {
+            node.params = node.params.replace(/^l-/, `${cssPrefix}-`);
+          }
+        }
+
+        if (node.type === 'rule') {
+          node.selector = rewriteSelector(node.selector, elementPrefix, cssPrefix);
+        }
+
+        if (node.type === 'decl') {
+          if (node.prop.startsWith('--l-')) {
+            node.prop = node.prop.replace(/^--l-/, `--${cssPrefix}-`);
+          }
+
+          if (node.value.includes('l-')) {
+            node.value = rewriteValue(node.value, cssPrefix);
+          }
+        }
+      });
+    },
+  };
+};
+
+plugin.postcss = true;
+
+function rewriteSelector(selector, elementPrefix, cssPrefix) {
+  let result = selector;
+  result = result.replace(/\.l-/g, `.${cssPrefix}-`);
+  result = result.replace(/(^|[\s,>+~(])l-/gm, `$1${elementPrefix}-`);
+  return result;
+}
+
+function rewriteValue(value, cssPrefix) {
+  let result = value;
+  result = result.replaceAll('--l-', `--${cssPrefix}-`);
+  result = result.replace(/(?<![-\w])l-/g, `${cssPrefix}-`);
+  return result;
+}
+
+export default plugin;

package/vite-plugin.ts

@@ -0,0 +1,29 @@
+import type { Plugin } from 'vite-plus';
+import postcssPrefix from './postcss-plugin-prefix.js';
+
+export interface LuxenOptions {
+  /** Custom element tag name prefix. Default `'l'`. */
+  elementPrefix?: string;
+  /** CSS class/token/keyframe prefix. Default `'l'`. */
+  cssPrefix?: string;
+}
+
+export default function luxen(options: LuxenOptions = {}): Plugin {
+  const elementPrefix = options.elementPrefix || 'l';
+  const cssPrefix = options.cssPrefix || 'l';
+
+  return {
+    name: 'luxen',
+
+    config() {
+      if (elementPrefix === 'l' && cssPrefix === 'l') return;
+      return {
+        css: {
+          postcss: {
+            plugins: [postcssPrefix({ elementPrefix, cssPrefix })],
+          },
+        },
+      };
+    },
+  };
+}