@adia-ai/web-modules 0.4.8 → 0.4.9

package/CHANGELOG.md

@@ -11,6 +11,65 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.4.9] - 2026-05-13
+
+### Added — `<editor-sidebar>` `[persist]` attribute (§91c, FEEDBACK-04 #6)
+
+Closes FEEDBACK-04 claim #6 discoverability gap. `<editor-sidebar>` has persisted pane width to `localStorage` since the module shipped, keyed by `[name]` (with `[slot]` fallback). The consumer's mental model expected `[persist="dts-layout"]` — that attribute name better describes what the surface does. v0.4.9 adds `[persist]` as the preferred attribute:
+
+```html
+<!-- Preferred (v0.4.9+) -->
+<editor-sidebar slot="leading" collapsible persist="dts-layout">
+  <pane-ui resizable>...</pane-ui>
+</editor-sidebar>
+
+<!-- Back-compat (v0.4.x) — still works -->
+<editor-sidebar slot="leading" collapsible name="dts-layout">
+  <pane-ui resizable>...</pane-ui>
+</editor-sidebar>
+```
+
+Both map to the same `localStorage["adia-editor-sidebar-dts-layout"]` namespace. Precedence is `[persist]` > `[name]` > `[slot]` — if both `[persist]` and `[name]` are set, `[persist]` wins (more descriptive attribute beats the legacy alias). The `sidebar-toggle` event's `detail.name` reflects the chosen key.
+
+`[name]` is now documented as deprecated; not scheduled for removal in v0.5.x.
+
+**Migration:**
+
+```diff
+- <editor-sidebar collapsible name="dts-layout">
++ <editor-sidebar collapsible persist="dts-layout">
+```
+
+### Added — `isFocusInInput()` utility on `@adia-ai/web-modules/editor` (§90, FEEDBACK-04 P2 #5)
+
+`FEEDBACK-04--adia-ui--2026-05-13.md` item #5: consumer building global keyboard shortcuts for an editor app hit the TypeScript ergonomics gap on `document.activeElement.isContentEditable` (the `Element` type doesn't have `isContentEditable`; only `HTMLElement` does). Every consumer reimplements the cast boilerplate.
+
+Ships `isFocusInInput()` as a small helper:
+
+```ts
+import { isFocusInInput } from '@adia-ai/web-modules/editor';
+
+document.addEventListener('keydown', (e) => {
+  if (isFocusInInput()) return;  // user is typing — don't fire shortcut
+  if (e.key === '/') openCommandPalette();
+});
+```
+
+Returns `true` when focus is inside `<input>` / `<textarea>` / any `contenteditable` host / or an AdiaUI text-input primitive (`<input-ui>`, `<textarea-ui>`, `<otp-input-ui>`, `<search-ui>`). The AdiaUI tag-name checks catch focus that lands on the host element (not just the inner native input).
+
+**Files:**
+- NEW `packages/web-modules/editor/utils.js` — implementation
+- NEW `packages/web-modules/editor/utils.d.ts` — types
+- NEW `packages/web-modules/editor/index.d.ts` — barrel re-export of the editor module types incl. `isFocusInInput`
+- `packages/web-modules/editor/index.js` — re-export
+- `packages/web-modules/package.json` — `./editor` exports gains `types` conditional; new explicit `./editor/utils` entry for direct subpath import
+
+Two reachable import paths:
+- `import { isFocusInInput } from '@adia-ai/web-modules/editor';` (via barrel)
+- `import { isFocusInInput } from '@adia-ai/web-modules/editor/utils';` (direct subpath)
+
+Both carry types via the new `types` conditionals.
+
 ## [0.4.8] - 2026-05-12
 
 ### Added — TypeScript declarations for all web-modules (FEEDBACK-02 #1, v0.4.8)

package/editor/editor-sidebar/editor-sidebar.a2ui.json

@@ -21,6 +21,16 @@
     "component": {
       "const": "EditorSidebar"
     },
+    "name": {
+      "description": "Alias for [persist]; kept for v0.4.x back-compat. Deprecated —\nnew code should use [persist]. If both are set, [persist] wins.\n",
+      "type": "string",
+      "default": ""
+    },
+    "persist": {
+      "description": "localStorage key suffix. When set, the sidebar persists its pane\nwidth across reloads under `adia-editor-sidebar-{persist}`.\nPreferred over the [name] alias kept for v0.4.x back-compat.\nDefaults to [name] then [slot] if neither set.\n",
+      "type": "string",
+      "default": ""
+    },
     "resizing": {
       "description": "Reflected — set during an active pointer-drag of the pane's\nresize handle. Used to disable transitions and visual treatments\nthat would feel laggy during drag.\n",
       "type": "boolean",

package/editor/editor-sidebar/editor-sidebar.d.ts

@@ -38,6 +38,16 @@ export type EditorSidebarSidebarToggleEvent = CustomEvent<EditorSidebarSidebarTo
 export class UIEditorSidebar extends UIElement {
   /** Reflected — set when inner <pane-ui> width is at or below 96px snap threshold. */
   collapsed: boolean;
+  /** Alias for [persist]; kept for v0.4.x back-compat. Deprecated —
+new code should use [persist]. If both are set, [persist] wins.
+ */
+  name: string;
+  /** localStorage key suffix. When set, the sidebar persists its pane
+width across reloads under `adia-editor-sidebar-{persist}`.
+Preferred over the [name] alias kept for v0.4.x back-compat.
+Defaults to [name] then [slot] if neither set.
+ */
+  persist: string;
   /** Reflected — set during an active pointer-drag of the pane's
 resize handle. Used to disable transitions and visual treatments
 that would feel laggy during drag.

package/editor/editor-sidebar/editor-sidebar.js

@@ -25,8 +25,11 @@
  *   [slot="leading"|"trailing"]  — required, drives localStorage
  *                                  namespacing
  *   [collapsible]                — opts in to programmatic collapse
- *   [name="<id>"]                — optional override for the
- *                                  localStorage key (defaults to slot)
+ *   [persist="<id>"]             — optional override for the localStorage
+ *                                  key (defaults to slot). Preferred over
+ *                                  [name]; if both set, [persist] wins.
+ *   [name="<id>"]                — alias for [persist]; kept for v0.4.x
+ *                                  back-compat. Deprecated; prefer [persist].
  *
  * Reflected attributes:
  *   [collapsed]  — set when inner pane width ≤ SNAP_THRESHOLD
@@ -69,10 +72,14 @@ class EditorSidebar extends UIElement {
     this.#pane = this.querySelector('pane-ui');
     if (!this.#pane) return;
 
-    // Resolve storage key
+    // Resolve storage key. Source of truth is [persist], with [name] as an
+    // alias kept for back-compat — both map to the same `${STORAGE_PREFIX}${key}`
+    // localStorage namespace. If both are set, [persist] wins (more descriptive
+    // attribute should beat the legacy alias). Final fallback is [slot] so an
+    // un-named sidebar still namespaces itself per-position.
     const slot = this.getAttribute('slot') || 'leading';
-    const name = this.getAttribute('name') || slot;
-    this.#storageKey = `${STORAGE_PREFIX}${name}`;
+    const key = this.getAttribute('persist') || this.getAttribute('name') || slot;
+    this.#storageKey = `${STORAGE_PREFIX}${key}`;
 
     // Restore persisted width
     this.#restoreWidth();
@@ -169,7 +176,7 @@ class EditorSidebar extends UIElement {
 
   #emitToggle() {
     const slot = this.getAttribute('slot') || 'leading';
-    const name = this.getAttribute('name') || slot;
+    const name = this.getAttribute('persist') || this.getAttribute('name') || slot;
     this.dispatchEvent(new CustomEvent('sidebar-toggle', {
       bubbles: true,
       detail: { name, expanded: !this.collapsed },

package/editor/editor-sidebar/editor-sidebar.yaml

@@ -37,6 +37,20 @@ props:
     type: boolean
     default: false
     reflect: true
+  persist:
+    description: |
+      localStorage key suffix. When set, the sidebar persists its pane
+      width across reloads under `adia-editor-sidebar-{persist}`.
+      Preferred over the [name] alias kept for v0.4.x back-compat.
+      Defaults to [name] then [slot] if neither set.
+    type: string
+    default: ""
+  name:
+    description: |
+      Alias for [persist]; kept for v0.4.x back-compat. Deprecated —
+      new code should use [persist]. If both are set, [persist] wins.
+    type: string
+    default: ""
 
 events:
   sidebar-toggle:

package/editor/index.d.ts

@@ -0,0 +1,5 @@
+export { EditorShell } from './editor-shell/editor-shell.js';
+export { EditorToolbar } from './editor-toolbar/editor-toolbar.js';
+export { EditorCanvas } from './editor-canvas/editor-canvas.js';
+export { EditorSidebar } from './editor-sidebar/editor-sidebar.js';
+export { isFocusInInput } from './utils.js';

package/editor/index.js

@@ -2,3 +2,4 @@ export { EditorShell } from './editor-shell/editor-shell.js';
 export { EditorToolbar } from './editor-toolbar/editor-toolbar.js';
 export { EditorCanvas } from './editor-canvas/editor-canvas.js';
 export { EditorSidebar } from './editor-sidebar/editor-sidebar.js';
+export { isFocusInInput } from './utils.js';

package/editor/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * True when keyboard focus is currently inside a text-input surface
+ * (`<input>`, `<textarea>`, any `contenteditable` host, or an AdiaUI
+ * `<input-ui>` / `<textarea-ui>` / `<otp-input-ui>` / `<search-ui>`).
+ * Use this to guard global keyboard shortcuts so they don't fire while
+ * the user is typing.
+ */
+export function isFocusInInput(): boolean;

package/editor/utils.js

@@ -0,0 +1,47 @@
+/**
+ * Editor utilities — small helpers paired with the editor-shell cluster.
+ *
+ * Kept here (not in `@adia-ai/web-components/core`) because they're
+ * editor-cluster-shaped — they're useful when implementing the kind of
+ * keyboard model an editor app needs (panel-aware shortcuts that
+ * shouldn't fire while the user is typing). Core is for primitive
+ * authoring; this is for product-shell wiring.
+ */
+
+/**
+ * True when keyboard focus is currently inside a text-input surface
+ * (`<input>`, `<textarea>`, or any `contenteditable` host). Use this
+ * to guard global keyboard shortcuts so they don't fire while the user
+ * is typing.
+ *
+ * Works against the standard DOM `document.activeElement` + the
+ * `HTMLElement.isContentEditable` property, with the TypeScript cast
+ * boilerplate hidden:
+ *
+ *     // Before
+ *     const active = document.activeElement as HTMLElement | null;
+ *     if (active?.tagName === 'INPUT' || active?.isContentEditable) return;
+ *
+ *     // After
+ *     if (isFocusInInput()) return;
+ *
+ * Also recognizes the AdiaUI text-input primitives (`<input-ui>`,
+ * `<textarea-ui>`, `<otp-input-ui>`, `<search-ui>`) — they extend
+ * `UIFormElement` and host a focused native `<input>`/`<textarea>` in
+ * their light-DOM subtree, but a stricter check on `tagName` would miss
+ * focus that lands on the host element directly.
+ *
+ * @returns {boolean}
+ */
+export function isFocusInInput() {
+  const active = /** @type {HTMLElement | null} */ (document.activeElement);
+  if (!active) return false;
+  const tag = active.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA') return true;
+  if (active.isContentEditable) return true;
+  // AdiaUI text-input primitives — focus may land on the host element
+  // when the inner native input isn't yet mounted, or on the inner
+  // native input itself (caught above).
+  if (tag === 'INPUT-UI' || tag === 'TEXTAREA-UI' || tag === 'OTP-INPUT-UI' || tag === 'SEARCH-UI') return true;
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "AdiaUI composite custom elements — shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {
@@ -11,7 +11,14 @@
     "./chat": "./chat/index.js",
     "./chat/*": "./chat/*/*.js",
     "./chat/*.css": "./chat/*/*.css",
-    "./editor": "./editor/index.js",
+    "./editor": {
+      "types": "./editor/index.d.ts",
+      "default": "./editor/index.js"
+    },
+    "./editor/utils": {
+      "types": "./editor/utils.d.ts",
+      "default": "./editor/utils.js"
+    },
     "./editor/*": "./editor/*/*.js",
     "./editor/*.css": "./editor/*/*.css",
     "./simple": "./simple/index.js",