@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/utils/canvas-reveal.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Canvas visibility for elements that start hidden on the published site
+ * (AGL-592).
+ *
+ * An element carrying {@link Aglyn.ELEMENT_HIDDEN_CLASS} — a mega-menu panel,
+ * a drawer, anything an interaction reveals at runtime — is `display: none`
+ * on the live page from the first paint. The canvas hides it too, so what an
+ * author sees matches what a visitor sees, and then reveals it on demand so
+ * it can be designed.
+ *
+ * The decision is made HERE, in JS, and stamped on the element itself rather
+ * than expressed as a relationship between elements in a selector. A rule
+ * that hides `.aglyn-hidden` unless a marker sits on its DOM PARENT depends
+ * on the rendered tree matching the node tree one-for-one, which it does not:
+ * any component whose render wraps its children puts a wrapper between the
+ * marked element and the hidden one, and the reveal silently stops matching.
+ * A flag on the hidden element cannot come apart that way.
+ */
+/** Node shape these helpers read; the canvas node class satisfies it. */
+type RevealNode = {
+    $id?: string;
+    className?: string;
+    hidden?: boolean;
+    props?: Record<string, unknown>;
+    parent?: RevealNode;
+} | null;
+/**
+ * Whether a node starts hidden on the published site — the state the eye
+ * affordance in the hierarchy reports and the canvas reveal overrides.
+ */
+export declare function isNodeHiddenOnSite(node: RevealNode): boolean;
+/**
+ * Whether the canvas shows a hidden node right now.
+ *
+ * Two ways in, and both are canvas-only:
+ *
+ * - the author turned it on from the hierarchy, so its id sits in
+ *   `revealedNodeIds`;
+ * - the selection is inside the node's PARENT — the wrapper, the trigger
+ *   beside it, the node itself or anything within it — which reveals a panel
+ *   for as long as it is being worked on without asking for a click.
+ *
+ * The selection path stops at the parent rather than walking further up
+ * because every node is inside the root: a check against an ancestor would
+ * show every hidden element on the page the moment anything was selected. A
+ * node whose parent IS the root falls back to its own subtree for the same
+ * reason.
+ */
+export declare function isNodeRevealedOnCanvas(node: RevealNode, revealedNodeIds?: readonly string[]): boolean;
+/**
+ * The reveal list with one node flipped. Returns a new array so the flag's
+ * subscribers see a changed value, and never mutates the one passed in.
+ */
+export declare function toggleRevealedNodeId(revealedNodeIds: readonly string[] | undefined, nodeId: string): string[];
+/**
+ * The class list a node would carry with the hidden class added or removed.
+ *
+ * Returns the props object to assign, or `null` when nothing would change —
+ * so a caller never writes an identical value and never puts a second copy of
+ * the class on an element that already has one.
+ *
+ * Reads and writes `props.className` only. `node.className` is also consulted
+ * when ASKING whether an element is hidden, because a component may
+ * contribute one of its own, but that is the component's business and not a
+ * value an author's toggle may edit.
+ */
+export declare function nodePropsWithHiddenOnSite(node: RevealNode, hidden: boolean): Record<string, unknown> | null;
+/**
+ * Whether an ANCESTOR already hides this node, so the published site never
+ * renders it whatever its own class list says.
+ *
+ * The hierarchy dims a hidden layer and everything under it — a container
+ * that does not ship takes its contents with it, and a full-strength child
+ * row inside a dimmed parent reads as "this one still ships", which is the
+ * opposite of true. Only the OUTERMOST hidden ancestor draws the dim: CSS
+ * opacity multiplies through nesting, so letting each hidden level apply its
+ * own would fade a panel inside a hidden drawer to near-invisible.
+ */
+export declare function isAncestorHiddenOnSite(node: RevealNode): boolean;
+/**
+ * Whether the AUTHOR has hidden this element.
+ *
+ * The plain switch behind the eye on the hierarchy row: `display: none` on
+ * the canvas and on the published site, with nothing that reveals it.
+ * Deliberately not {@link isNodeHiddenOnSite}, which asks a different
+ * question — "does this start hidden for an interaction to show" — about a
+ * class that is part of a runtime contract.
+ */
+export declare function isNodeHiddenByAuthor(node: RevealNode): boolean;
+/**
+ * Whether an ANCESTOR is hidden, by either switch, so the published site
+ * never renders this node whatever its own state says.
+ *
+ * Replaces the class-only walk: an element inside a container the author hid
+ * is exactly as absent as one inside a container that starts hidden, and the
+ * hierarchy dims both the same way.
+ */
+export declare function isAncestorHidden(node: RevealNode): boolean;
+export {};

package/src/lib/utils/canvas-reveal.js

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { ELEMENT_HIDDEN_CLASS, NODE_ROOT_ID } from "@aglyn/aglyn";
+import * as Besigner from "@aglyn/besigner";
+/**
+ * A node's ancestors, innermost first, visiting each at most once.
+ *
+ * The chain a canvas document offers is NOT acyclic. A stored document's root
+ * is its own parent — `CanvasManager.processNodesToDenormalized` builds it
+ * through `denormalizeNodes([{ $id: NODE_ROOT_ID, … }], NODE_ROOT_ID)`, and
+ * `denormalizeNodes` stamps its `parentId` argument onto every node it writes,
+ * the root included — and `AglynNode.parent` resolves that id straight back to
+ * the root. So `current = current.parent` has no null to arrive at: it settles
+ * on the root and stays there.
+ *
+ * That is a synchronous infinite loop on the renderer's main thread, not a
+ * slow walk. It costs the whole tab: Chrome stops answering input and script
+ * evaluation entirely and the page has to be closed.
+ *
+ * The visited set is keyed by node identity, so it terminates on ANY parent
+ * chain rather than only on the root's — a document whose nodes parent each
+ * other yields a wrong dim on one row instead of a locked browser.
+ */ function* ancestorsOf(node) {
+    const seen = new Set();
+    let current = node == null ? void 0 : node.parent;
+    while(current){
+        var _current_$id;
+        const key = (_current_$id = current.$id) != null ? _current_$id : current;
+        if (seen.has(key)) return;
+        seen.add(key);
+        yield current;
+        current = current.parent;
+    }
+}
+/** The class names a node contributes to its rendered element. */ function nodeClassNames(node) {
+    var _node_props;
+    return [
+        node == null ? void 0 : (_node_props = node.props) == null ? void 0 : _node_props['className'],
+        node == null ? void 0 : node.className
+    ].filter((value)=>typeof value === 'string').flatMap((value)=>value.split(/\s+/)).filter(Boolean);
+}
+/**
+ * Whether a node starts hidden on the published site — the state the eye
+ * affordance in the hierarchy reports and the canvas reveal overrides.
+ */ export function isNodeHiddenOnSite(node) {
+    return nodeClassNames(node).includes(ELEMENT_HIDDEN_CLASS);
+}
+/**
+ * Whether the canvas shows a hidden node right now.
+ *
+ * Two ways in, and both are canvas-only:
+ *
+ * - the author turned it on from the hierarchy, so its id sits in
+ *   `revealedNodeIds`;
+ * - the selection is inside the node's PARENT — the wrapper, the trigger
+ *   beside it, the node itself or anything within it — which reveals a panel
+ *   for as long as it is being worked on without asking for a click.
+ *
+ * The selection path stops at the parent rather than walking further up
+ * because every node is inside the root: a check against an ancestor would
+ * show every hidden element on the page the moment anything was selected. A
+ * node whose parent IS the root falls back to its own subtree for the same
+ * reason.
+ */ export function isNodeRevealedOnCanvas(node, revealedNodeIds) {
+    if (!node) return false;
+    if (revealedNodeIds == null ? void 0 : revealedNodeIds.some((id)=>id === node.$id)) return true;
+    const parent = node.parent;
+    const scope = parent && parent.$id !== NODE_ROOT_ID ? parent : node;
+    return Besigner.focus.isNodeOrDescendantSelected(scope);
+}
+/**
+ * The reveal list with one node flipped. Returns a new array so the flag's
+ * subscribers see a changed value, and never mutates the one passed in.
+ */ export function toggleRevealedNodeId(revealedNodeIds, nodeId) {
+    const current = revealedNodeIds != null ? revealedNodeIds : [];
+    return current.some((id)=>id === nodeId) ? current.filter((id)=>id !== nodeId) : [
+        ...current,
+        nodeId
+    ];
+}
+/**
+ * The class list a node would carry with the hidden class added or removed.
+ *
+ * Returns the props object to assign, or `null` when nothing would change —
+ * so a caller never writes an identical value and never puts a second copy of
+ * the class on an element that already has one.
+ *
+ * Reads and writes `props.className` only. `node.className` is also consulted
+ * when ASKING whether an element is hidden, because a component may
+ * contribute one of its own, but that is the component's business and not a
+ * value an author's toggle may edit.
+ */ export function nodePropsWithHiddenOnSite(node, hidden) {
+    var _ref, _node_props;
+    var _node_props1;
+    if (!node) return null;
+    const current = String((_ref = (_node_props1 = node.props) == null ? void 0 : _node_props1['className']) != null ? _ref : '').split(/\s+/).filter(Boolean);
+    const has = current.includes(ELEMENT_HIDDEN_CLASS);
+    if (has === hidden) return null;
+    const next = hidden ? [
+        ...current,
+        ELEMENT_HIDDEN_CLASS
+    ] : current.filter((name)=>name !== ELEMENT_HIDDEN_CLASS);
+    const props = _extends({}, (_node_props = node.props) != null ? _node_props : {});
+    if (next.length) props['className'] = next.join(' ');
+    else delete props['className'];
+    return props;
+}
+/**
+ * Whether an ANCESTOR already hides this node, so the published site never
+ * renders it whatever its own class list says.
+ *
+ * The hierarchy dims a hidden layer and everything under it — a container
+ * that does not ship takes its contents with it, and a full-strength child
+ * row inside a dimmed parent reads as "this one still ships", which is the
+ * opposite of true. Only the OUTERMOST hidden ancestor draws the dim: CSS
+ * opacity multiplies through nesting, so letting each hidden level apply its
+ * own would fade a panel inside a hidden drawer to near-invisible.
+ */ export function isAncestorHiddenOnSite(node) {
+    for (const ancestor of ancestorsOf(node)){
+        if (isNodeHiddenOnSite(ancestor)) return true;
+    }
+    return false;
+}
+/**
+ * Whether the AUTHOR has hidden this element.
+ *
+ * The plain switch behind the eye on the hierarchy row: `display: none` on
+ * the canvas and on the published site, with nothing that reveals it.
+ * Deliberately not {@link isNodeHiddenOnSite}, which asks a different
+ * question — "does this start hidden for an interaction to show" — about a
+ * class that is part of a runtime contract.
+ */ export function isNodeHiddenByAuthor(node) {
+    return Boolean(node == null ? void 0 : node.hidden);
+}
+/**
+ * Whether an ANCESTOR is hidden, by either switch, so the published site
+ * never renders this node whatever its own state says.
+ *
+ * Replaces the class-only walk: an element inside a container the author hid
+ * is exactly as absent as one inside a container that starts hidden, and the
+ * hierarchy dims both the same way.
+ */ export function isAncestorHidden(node) {
+    for (const ancestor of ancestorsOf(node)){
+        if (isNodeHiddenByAuthor(ancestor) || isNodeHiddenOnSite(ancestor)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+//# sourceMappingURL=canvas-reveal.js.map

package/src/lib/utils/canvas-reveal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/utils/canvas-reveal.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type * as Aglyn from '@aglyn/aglyn'\nimport { ELEMENT_HIDDEN_CLASS, NODE_ROOT_ID } from '@aglyn/aglyn'\nimport * as Besigner from '@aglyn/besigner'\n\n/**\n * Canvas visibility for elements that start hidden on the published site\n * (AGL-592).\n *\n * An element carrying {@link Aglyn.ELEMENT_HIDDEN_CLASS} — a mega-menu panel,\n * a drawer, anything an interaction reveals at runtime — is `display: none`\n * on the live page from the first paint. The canvas hides it too, so what an\n * author sees matches what a visitor sees, and then reveals it on demand so\n * it can be designed.\n *\n * The decision is made HERE, in JS, and stamped on the element itself rather\n * than expressed as a relationship between elements in a selector. A rule\n * that hides `.aglyn-hidden` unless a marker sits on its DOM PARENT depends\n * on the rendered tree matching the node tree one-for-one, which it does not:\n * any component whose render wraps its children puts a wrapper between the\n * marked element and the hidden one, and the reveal silently stops matching.\n * A flag on the hidden element cannot come apart that way.\n */\n\n/** Node shape these helpers read; the canvas node class satisfies it. */\ntype RevealNode = {\n  $id?: string\n  className?: string\n  hidden?: boolean\n  props?: Record<string, unknown>\n  parent?: RevealNode\n} | null\n\n/**\n * A node's ancestors, innermost first, visiting each at most once.\n *\n * The chain a canvas document offers is NOT acyclic. A stored document's root\n * is its own parent — `CanvasManager.processNodesToDenormalized` builds it\n * through `denormalizeNodes([{ $id: NODE_ROOT_ID, … }], NODE_ROOT_ID)`, and\n * `denormalizeNodes` stamps its `parentId` argument onto every node it writes,\n * the root included — and `AglynNode.parent` resolves that id straight back to\n * the root. So `current = current.parent` has no null to arrive at: it settles\n * on the root and stays there.\n *\n * That is a synchronous infinite loop on the renderer's main thread, not a\n * slow walk. It costs the whole tab: Chrome stops answering input and script\n * evaluation entirely and the page has to be closed.\n *\n * The visited set is keyed by node identity, so it terminates on ANY parent\n * chain rather than only on the root's — a document whose nodes parent each\n * other yields a wrong dim on one row instead of a locked browser.\n */\nfunction* ancestorsOf(node: RevealNode): Generator<NonNullable<RevealNode>> {\n  const seen = new Set<unknown>()\n  let current = node?.parent\n  while (current) {\n    const key = current.$id ?? current\n    if (seen.has(key)) return\n    seen.add(key)\n    yield current\n    current = current.parent\n  }\n}\n\n/** The class names a node contributes to its rendered element. */\nfunction nodeClassNames(node: RevealNode): string[] {\n  return [node?.props?.['className'], node?.className]\n    .filter((value): value is string => typeof value === 'string')\n    .flatMap((value) => value.split(/\\s+/))\n    .filter(Boolean)\n}\n\n/**\n * Whether a node starts hidden on the published site — the state the eye\n * affordance in the hierarchy reports and the canvas reveal overrides.\n */\nexport function isNodeHiddenOnSite(node: RevealNode): boolean {\n  return nodeClassNames(node).includes(ELEMENT_HIDDEN_CLASS)\n}\n\n/**\n * Whether the canvas shows a hidden node right now.\n *\n * Two ways in, and both are canvas-only:\n *\n * - the author turned it on from the hierarchy, so its id sits in\n *   `revealedNodeIds`;\n * - the selection is inside the node's PARENT — the wrapper, the trigger\n *   beside it, the node itself or anything within it — which reveals a panel\n *   for as long as it is being worked on without asking for a click.\n *\n * The selection path stops at the parent rather than walking further up\n * because every node is inside the root: a check against an ancestor would\n * show every hidden element on the page the moment anything was selected. A\n * node whose parent IS the root falls back to its own subtree for the same\n * reason.\n */\nexport function isNodeRevealedOnCanvas(\n  node: RevealNode,\n  revealedNodeIds?: readonly string[],\n): boolean {\n  if (!node) return false\n  if (revealedNodeIds?.some((id) => id === node.$id)) return true\n  const parent = node.parent\n  const scope = parent && parent.$id !== NODE_ROOT_ID ? parent : node\n  return Besigner.focus.isNodeOrDescendantSelected(scope as never)\n}\n\n/**\n * The reveal list with one node flipped. Returns a new array so the flag's\n * subscribers see a changed value, and never mutates the one passed in.\n */\nexport function toggleRevealedNodeId(\n  revealedNodeIds: readonly string[] | undefined,\n  nodeId: string,\n): string[] {\n  const current = revealedNodeIds ?? []\n  return current.some((id) => id === nodeId)\n    ? current.filter((id) => id !== nodeId)\n    : [...current, nodeId]\n}\n\n/**\n * The class list a node would carry with the hidden class added or removed.\n *\n * Returns the props object to assign, or `null` when nothing would change —\n * so a caller never writes an identical value and never puts a second copy of\n * the class on an element that already has one.\n *\n * Reads and writes `props.className` only. `node.className` is also consulted\n * when ASKING whether an element is hidden, because a component may\n * contribute one of its own, but that is the component's business and not a\n * value an author's toggle may edit.\n */\nexport function nodePropsWithHiddenOnSite(\n  node: RevealNode,\n  hidden: boolean,\n): Record<string, unknown> | null {\n  if (!node) return null\n  const current = String(node.props?.['className'] ?? '')\n    .split(/\\s+/)\n    .filter(Boolean)\n  const has = current.includes(ELEMENT_HIDDEN_CLASS)\n  if (has === hidden) return null\n  const next = hidden\n    ? [...current, ELEMENT_HIDDEN_CLASS]\n    : current.filter((name) => name !== ELEMENT_HIDDEN_CLASS)\n  const props: Record<string, unknown> = { ...(node.props ?? {}) }\n  if (next.length) props['className'] = next.join(' ')\n  else delete props['className']\n  return props\n}\n\n/**\n * Whether an ANCESTOR already hides this node, so the published site never\n * renders it whatever its own class list says.\n *\n * The hierarchy dims a hidden layer and everything under it — a container\n * that does not ship takes its contents with it, and a full-strength child\n * row inside a dimmed parent reads as \"this one still ships\", which is the\n * opposite of true. Only the OUTERMOST hidden ancestor draws the dim: CSS\n * opacity multiplies through nesting, so letting each hidden level apply its\n * own would fade a panel inside a hidden drawer to near-invisible.\n */\nexport function isAncestorHiddenOnSite(node: RevealNode): boolean {\n  for (const ancestor of ancestorsOf(node)) {\n    if (isNodeHiddenOnSite(ancestor)) return true\n  }\n  return false\n}\n\n\n/**\n * Whether the AUTHOR has hidden this element.\n *\n * The plain switch behind the eye on the hierarchy row: `display: none` on\n * the canvas and on the published site, with nothing that reveals it.\n * Deliberately not {@link isNodeHiddenOnSite}, which asks a different\n * question — \"does this start hidden for an interaction to show\" — about a\n * class that is part of a runtime contract.\n */\nexport function isNodeHiddenByAuthor(node: RevealNode): boolean {\n  return Boolean(node?.hidden)\n}\n\n/**\n * Whether an ANCESTOR is hidden, by either switch, so the published site\n * never renders this node whatever its own state says.\n *\n * Replaces the class-only walk: an element inside a container the author hid\n * is exactly as absent as one inside a container that starts hidden, and the\n * hierarchy dims both the same way.\n */\nexport function isAncestorHidden(node: RevealNode): boolean {\n  for (const ancestor of ancestorsOf(node)) {\n    if (isNodeHiddenByAuthor(ancestor) || isNodeHiddenOnSite(ancestor)) {\n      return true\n    }\n  }\n  return false\n}\n"],"names":["ELEMENT_HIDDEN_CLASS","NODE_ROOT_ID","Besigner","ancestorsOf","node","seen","Set","current","parent","key","$id","has","add","nodeClassNames","props","className","filter","value","flatMap","split","Boolean","isNodeHiddenOnSite","includes","isNodeRevealedOnCanvas","revealedNodeIds","some","id","scope","focus","isNodeOrDescendantSelected","toggleRevealedNodeId","nodeId","nodePropsWithHiddenOnSite","hidden","String","next","name","length","join","isAncestorHiddenOnSite","ancestor","isNodeHiddenByAuthor","isAncestorHidden"],"mappings":"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"}

package/src/lib/utils/describe-element.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * One derived statement about an element (AGL-2486).
+ *
+ * Every fact here is READ OFF the schema, never authored. That is the whole
+ * point: a component that changes its `restrictChildren` changes what the
+ * picker says about it in the same commit, whereas a sentence somebody typed
+ * about it in 2026 is wrong the moment the component moves and nothing
+ * fails. Prose is reserved for the things that genuinely cannot be derived.
+ */
+export interface ElementFact {
+    /** Stable key — a surface may order or style by it. Not persisted. */
+    id: string;
+    /** Short user-facing sentence. */
+    label: string;
+}
+export interface ElementDetail {
+    /** The picker item's own id (a preset id for drawer entries). */
+    $id?: string;
+    /** The component the item ultimately places. */
+    componentId?: string;
+    name: string;
+    category?: string;
+    /**
+     * Authored one-liner, when the schema carries one. ~22 of the 57 mui
+     * component schemas do, and most presets do; the rest show facts only.
+     * Deliberately NOT padded with generated filler — a thin honest entry
+     * beats an invented paragraph.
+     */
+    description?: string;
+    /** Derived, never authored. */
+    facts: ElementFact[];
+    /** Attribute labels the Attributes panel will offer for this element. */
+    attributes: string[];
+    /** Set only for components a plugin contributed. */
+    pluginId?: string;
+    /**
+     * Parents this element must sit inside, when its schema limits them.
+     *
+     * Derived from the same `restrictParent` the facts read. A preview uses it
+     * to explain itself: an element that only renders in context often draws
+     * nothing on its own, and an unexplained blank frame reads as a broken
+     * preview rather than as an honest one.
+     */
+    requiredParents: string[];
+}
+/**
+ * Everything the element pickers show about one element, derived from the
+ * registry (AGL-2486).
+ *
+ * Both surfaces call this — the Choose-element dialog and the docked
+ * Elements panel — so the content is designed once and only the
+ * presentation differs. A schema that says nothing produces an entry with a
+ * name, a category and no prose, which is the honest answer.
+ */
+export declare function describeElement(item: any): ElementDetail | null;
+export default describeElement;

package/src/lib/utils/describe-element.js

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { components, FEATURE_FLAG, LinealDirectiveFlag, schemaAcceptsChildren } from "@aglyn/aglyn";
+/** The mui bundle is the built-in set — not worth calling out as a plugin. */ const BUILT_IN_PLUGIN_IDS = new Set([
+    'mui'
+]);
+function label(componentId) {
+    var _components_getLabel;
+    if (!componentId) return undefined;
+    return (_components_getLabel = components.getLabel(componentId)) != null ? _components_getLabel : componentId;
+}
+/**
+ * The component ids named by a lineal directive of `directive` type, as
+ * labels. Mirrors the reading `confirmValidLinealRelationship` does at drop
+ * time, so what the detail view promises is what the canvas enforces.
+ */ function linealLabels(order, directive) {
+    if (!order) return [];
+    const [directiveType, definition] = order;
+    if (directiveType !== directive) return [];
+    const components = Array.isArray(definition) ? definition : definition == null ? void 0 : definition.components;
+    return (components != null ? components : []).map((id)=>label(id)).filter(Boolean);
+}
+function isEnabled(flag) {
+    return Boolean(flag) && Boolean(flag & FEATURE_FLAG.ENABLED);
+}
+function isDisabled(flag) {
+    return Boolean(flag) && Boolean(flag & FEATURE_FLAG.DISABLED);
+}
+/**
+ * The component schema a picker item ultimately places.
+ *
+ * Drawer entries are PRESETS — "FAQ" is three stacked Accordions — so the
+ * facts have to come from the component the preset builds on, while the
+ * name and description stay the preset's own. Matches how the drop path
+ * resolves a dragged preset before validating it.
+ */ function resolveComponentSchema(item) {
+    var _ref;
+    var _item_data;
+    const componentId = (_ref = item == null ? void 0 : (_item_data = item.data) == null ? void 0 : _item_data.componentId) != null ? _ref : item == null ? void 0 : item.$id;
+    if (!componentId) return {};
+    return {
+        componentId,
+        schema: components.getSchema(componentId)
+    };
+}
+/**
+ * Everything the element pickers show about one element, derived from the
+ * registry (AGL-2486).
+ *
+ * Both surfaces call this — the Choose-element dialog and the docked
+ * Elements panel — so the content is designed once and only the
+ * presentation differs. A schema that says nothing produces an entry with a
+ * name, a category and no prose, which is the honest answer.
+ */ export function describeElement(item) {
+    var _ref, _ref1, _ref2;
+    var _schema_flags, _schema_flags1, _schema_flags2;
+    if (!item) return null;
+    const { componentId, schema } = resolveComponentSchema(item);
+    const name = (item == null ? void 0 : item.label) || (item == null ? void 0 : item.displayName) || label(item == null ? void 0 : item.$id) || (item == null ? void 0 : item.$id) || 'Element';
+    const facts = [];
+    // 1. Can it hold anything? The single most useful thing to know before
+    //    dropping one, and the question the child contract already answers.
+    const acceptsChildren = schemaAcceptsChildren(schema);
+    facts.push({
+        id: 'children',
+        label: acceptsChildren ? 'Holds other elements' : 'Does not hold other elements'
+    });
+    // 2. Lineal relationships, both directions.
+    const onlyChildren = linealLabels(schema == null ? void 0 : schema.restrictChildren, LinealDirectiveFlag.LIMIT_TO);
+    if (onlyChildren.length) {
+        facts.push({
+            id: 'only-accepts',
+            label: `Only accepts ${onlyChildren.join(', ')}`
+        });
+    }
+    const noChildren = linealLabels(schema == null ? void 0 : schema.restrictChildren, LinealDirectiveFlag.DISALLOW);
+    if (noChildren.length) {
+        facts.push({
+            id: 'never-accepts',
+            label: `Will not accept ${noChildren.join(', ')}`
+        });
+    }
+    const onlyParents = linealLabels(schema == null ? void 0 : schema.restrictParent, LinealDirectiveFlag.LIMIT_TO);
+    if (onlyParents.length) {
+        facts.push({
+            id: 'only-inside',
+            label: `Must be placed inside ${onlyParents.join(' or ')}`
+        });
+    }
+    const notInside = linealLabels(schema == null ? void 0 : schema.restrictParent, LinealDirectiveFlag.DISALLOW);
+    if (notInside.length) {
+        facts.push({
+            id: 'never-inside',
+            label: `Cannot be placed inside ${notInside.join(', ')}`
+        });
+    }
+    // 3. How its content is edited.
+    if (isEnabled(schema == null ? void 0 : (_schema_flags = schema.flags) == null ? void 0 : _schema_flags.textEditable)) {
+        var _schema_flags3;
+        facts.push({
+            id: 'text-editable',
+            label: isEnabled(schema == null ? void 0 : (_schema_flags3 = schema.flags) == null ? void 0 : _schema_flags3.richTextEditable) ? 'Its text is edited on the canvas, with basic formatting' : 'Its text is edited directly on the canvas'
+        });
+    }
+    // 4. Limitations the editor imposes, where a flag turns one OFF. These are
+    //    the ones a user hits and cannot explain.
+    if (isDisabled(schema == null ? void 0 : (_schema_flags1 = schema.flags) == null ? void 0 : _schema_flags1.dragging)) {
+        facts.push({
+            id: 'no-drag',
+            label: 'Cannot be moved by dragging'
+        });
+    }
+    if (isDisabled(schema == null ? void 0 : (_schema_flags2 = schema.flags) == null ? void 0 : _schema_flags2.removing)) {
+        facts.push({
+            id: 'no-remove',
+            label: 'Cannot be deleted'
+        });
+    }
+    // 5. Provenance — a third-party element should say so, since removing the
+    //    plugin removes the element.
+    const pluginId = (_ref = schema == null ? void 0 : schema.pluginId) != null ? _ref : item == null ? void 0 : item.pluginId;
+    if (pluginId && !BUILT_IN_PLUGIN_IDS.has(pluginId)) {
+        facts.push({
+            id: 'plugin',
+            label: `Provided by the ${pluginId} plugin`
+        });
+    }
+    const attributes = ((_ref1 = schema == null ? void 0 : schema.attributes) != null ? _ref1 : []).map((attr)=>(attr == null ? void 0 : attr.label) || (attr == null ? void 0 : attr.name)).filter(Boolean);
+    return {
+        $id: item == null ? void 0 : item.$id,
+        componentId,
+        name,
+        category: (_ref2 = item == null ? void 0 : item.category) != null ? _ref2 : schema == null ? void 0 : schema.category,
+        // The item's own prose wins — a preset describes itself better than the
+        // component it is built from ("Three stacked question panels" vs
+        // "Header that expands to reveal its details").
+        description: (item == null ? void 0 : item.description) || (schema == null ? void 0 : schema.description) || undefined,
+        facts,
+        attributes,
+        requiredParents: onlyParents,
+        pluginId: pluginId && !BUILT_IN_PLUGIN_IDS.has(pluginId) ? pluginId : undefined
+    };
+}
+export default describeElement;
+
+//# sourceMappingURL=describe-element.js.map

package/src/lib/utils/describe-element.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/utils/describe-element.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type * as Aglyn from '@aglyn/aglyn'\nimport {\n  components,\n  FEATURE_FLAG,\n  LinealDirectiveFlag,\n  schemaAcceptsChildren,\n} from '@aglyn/aglyn'\n\n/**\n * One derived statement about an element (AGL-2486).\n *\n * Every fact here is READ OFF the schema, never authored. That is the whole\n * point: a component that changes its `restrictChildren` changes what the\n * picker says about it in the same commit, whereas a sentence somebody typed\n * about it in 2026 is wrong the moment the component moves and nothing\n * fails. Prose is reserved for the things that genuinely cannot be derived.\n */\nexport interface ElementFact {\n  /** Stable key — a surface may order or style by it. Not persisted. */\n  id: string\n  /** Short user-facing sentence. */\n  label: string\n}\n\nexport interface ElementDetail {\n  /** The picker item's own id (a preset id for drawer entries). */\n  $id?: string\n  /** The component the item ultimately places. */\n  componentId?: string\n  name: string\n  category?: string\n  /**\n   * Authored one-liner, when the schema carries one. ~22 of the 57 mui\n   * component schemas do, and most presets do; the rest show facts only.\n   * Deliberately NOT padded with generated filler — a thin honest entry\n   * beats an invented paragraph.\n   */\n  description?: string\n  /** Derived, never authored. */\n  facts: ElementFact[]\n  /** Attribute labels the Attributes panel will offer for this element. */\n  attributes: string[]\n  /** Set only for components a plugin contributed. */\n  pluginId?: string\n  /**\n   * Parents this element must sit inside, when its schema limits them.\n   *\n   * Derived from the same `restrictParent` the facts read. A preview uses it\n   * to explain itself: an element that only renders in context often draws\n   * nothing on its own, and an unexplained blank frame reads as a broken\n   * preview rather than as an honest one.\n   */\n  requiredParents: string[]\n}\n\n/** The mui bundle is the built-in set — not worth calling out as a plugin. */\nconst BUILT_IN_PLUGIN_IDS = new Set(['mui'])\n\nfunction label(componentId?: string): string | undefined {\n  if (!componentId) return undefined\n  return components.getLabel(componentId) ?? componentId\n}\n\n/**\n * The component ids named by a lineal directive of `directive` type, as\n * labels. Mirrors the reading `confirmValidLinealRelationship` does at drop\n * time, so what the detail view promises is what the canvas enforces.\n */\nfunction linealLabels(\n  order: Aglyn.ComponentsLinealOrder | undefined,\n  directive: Aglyn.LinealDirectiveFlag,\n): string[] {\n  if (!order) return []\n  const [directiveType, definition] = order\n  if (directiveType !== directive) return []\n  const components = Array.isArray(definition)\n    ? definition\n    : definition?.components\n  return (components ?? []).map((id) => label(id)).filter(Boolean) as string[]\n}\n\nfunction isEnabled(flag?: Aglyn.FEATURE_FLAG): boolean {\n  return Boolean(flag) && Boolean(flag & FEATURE_FLAG.ENABLED)\n}\n\nfunction isDisabled(flag?: Aglyn.FEATURE_FLAG): boolean {\n  return Boolean(flag) && Boolean(flag & FEATURE_FLAG.DISABLED)\n}\n\n/**\n * The component schema a picker item ultimately places.\n *\n * Drawer entries are PRESETS — \"FAQ\" is three stacked Accordions — so the\n * facts have to come from the component the preset builds on, while the\n * name and description stay the preset's own. Matches how the drop path\n * resolves a dragged preset before validating it.\n */\nfunction resolveComponentSchema(item: any): {\n  componentId?: string\n  schema?: Aglyn.ComponentSchema\n} {\n  const componentId = item?.data?.componentId ?? item?.$id\n  if (!componentId) return {}\n  return {\n    componentId,\n    schema: components.getSchema(componentId) as Aglyn.ComponentSchema,\n  }\n}\n\n/**\n * Everything the element pickers show about one element, derived from the\n * registry (AGL-2486).\n *\n * Both surfaces call this — the Choose-element dialog and the docked\n * Elements panel — so the content is designed once and only the\n * presentation differs. A schema that says nothing produces an entry with a\n * name, a category and no prose, which is the honest answer.\n */\nexport function describeElement(item: any): ElementDetail | null {\n  if (!item) return null\n\n  const { componentId, schema } = resolveComponentSchema(item)\n  const name =\n    item?.label ||\n    item?.displayName ||\n    label(item?.$id) ||\n    item?.$id ||\n    'Element'\n\n  const facts: ElementFact[] = []\n\n  // 1. Can it hold anything? The single most useful thing to know before\n  //    dropping one, and the question the child contract already answers.\n  const acceptsChildren = schemaAcceptsChildren(schema)\n  facts.push({\n    id: 'children',\n    label: acceptsChildren\n      ? 'Holds other elements'\n      : 'Does not hold other elements',\n  })\n\n  // 2. Lineal relationships, both directions.\n  const onlyChildren = linealLabels(\n    schema?.restrictChildren,\n    LinealDirectiveFlag.LIMIT_TO,\n  )\n  if (onlyChildren.length) {\n    facts.push({\n      id: 'only-accepts',\n      label: `Only accepts ${onlyChildren.join(', ')}`,\n    })\n  }\n  const noChildren = linealLabels(\n    schema?.restrictChildren,\n    LinealDirectiveFlag.DISALLOW,\n  )\n  if (noChildren.length) {\n    facts.push({\n      id: 'never-accepts',\n      label: `Will not accept ${noChildren.join(', ')}`,\n    })\n  }\n  const onlyParents = linealLabels(\n    schema?.restrictParent,\n    LinealDirectiveFlag.LIMIT_TO,\n  )\n  if (onlyParents.length) {\n    facts.push({\n      id: 'only-inside',\n      label: `Must be placed inside ${onlyParents.join(' or ')}`,\n    })\n  }\n  const notInside = linealLabels(\n    schema?.restrictParent,\n    LinealDirectiveFlag.DISALLOW,\n  )\n  if (notInside.length) {\n    facts.push({\n      id: 'never-inside',\n      label: `Cannot be placed inside ${notInside.join(', ')}`,\n    })\n  }\n\n  // 3. How its content is edited.\n  if (isEnabled(schema?.flags?.textEditable)) {\n    facts.push({\n      id: 'text-editable',\n      label: isEnabled(schema?.flags?.richTextEditable)\n        ? 'Its text is edited on the canvas, with basic formatting'\n        : 'Its text is edited directly on the canvas',\n    })\n  }\n\n  // 4. Limitations the editor imposes, where a flag turns one OFF. These are\n  //    the ones a user hits and cannot explain.\n  if (isDisabled(schema?.flags?.dragging)) {\n    facts.push({ id: 'no-drag', label: 'Cannot be moved by dragging' })\n  }\n  if (isDisabled(schema?.flags?.removing)) {\n    facts.push({ id: 'no-remove', label: 'Cannot be deleted' })\n  }\n\n  // 5. Provenance — a third-party element should say so, since removing the\n  //    plugin removes the element.\n  const pluginId = schema?.pluginId ?? item?.pluginId\n  if (pluginId && !BUILT_IN_PLUGIN_IDS.has(pluginId)) {\n    facts.push({ id: 'plugin', label: `Provided by the ${pluginId} plugin` })\n  }\n\n  const attributes = (schema?.attributes ?? [])\n    .map((attr: any) => attr?.label || attr?.name)\n    .filter(Boolean)\n\n  return {\n    $id: item?.$id,\n    componentId,\n    name,\n    category: (item?.category ?? schema?.category) as string,\n    // The item's own prose wins — a preset describes itself better than the\n    // component it is built from (\"Three stacked question panels\" vs\n    // \"Header that expands to reveal its details\").\n    description: item?.description || schema?.description || undefined,\n    facts,\n    attributes,\n    requiredParents: onlyParents,\n    pluginId: pluginId && !BUILT_IN_PLUGIN_IDS.has(pluginId) ? pluginId : undefined,\n  }\n}\n\nexport default describeElement\n"],"names":["components","FEATURE_FLAG","LinealDirectiveFlag","schemaAcceptsChildren","BUILT_IN_PLUGIN_IDS","Set","label","componentId","undefined","getLabel","linealLabels","order","directive","directiveType","definition","Array","isArray","map","id","filter","Boolean","isEnabled","flag","ENABLED","isDisabled","DISABLED","resolveComponentSchema","item","data","$id","schema","getSchema","describeElement","name","displayName","facts","acceptsChildren","push","onlyChildren","restrictChildren","LIMIT_TO","length","join","noChildren","DISALLOW","onlyParents","restrictParent","notInside","flags","textEditable","richTextEditable","dragging","removing","pluginId","has","attributes","attr","category","description","requiredParents"],"mappings":"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"}

package/src/lib/utils/device-preview-styles.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { Theme } from '@aglyn/shared-ui-theme';
+/**
+ * Artboard device preview styling (AGL-581).
+ *
+ * CSS media queries always evaluate against the BROWSER viewport, so a
+ * narrowed artboard never triggered visibility bands
+ * (`@media (max-width:599.95px)` in node sx), breakpoint-scoped sx
+ * values (`{ xs, sm, md }`), or MUI's own breakpoint-derived component
+ * styles. When a device is selected in the toolbar the canvas now pins
+ * both mechanisms to the device's width:
+ *
+ * - `resolveSxForDeviceWidth` statically evaluates width-only `@media`
+ *   keys in node sx: matching slices inline where the key sat (keeping
+ *   cascade order), off-device slices drop. Applied per-Leaf through
+ *   `LeafSxTransformContext` — canvas only.
+ * - `createDevicePinnedTheme` rebuilds the canvas theme's breakpoint
+ *   helpers so every `theme.breakpoints.up/down/...` query is forced
+ *   always-true or never-true for the device width. Responsive sx
+ *   objects, Stack/Grid responsive props, and component styleOverrides
+ *   all resolve through these helpers at render time.
+ *
+ * Fluid Responsive (the default) provides neither, so the canvas keeps
+ * today's real-viewport behavior; the published tenant never sees any
+ * of this.
+ *
+ * The width each device simulates is `devicePreviewWidth`, which lives in
+ * `@aglyn/besigner` with the device flags so that anything auditing a page
+ * at the switcher's widths reads the same numbers the canvas pins to.
+ */
+export { DEVICE_PREVIEW_XS_WIDTH, devicePreviewWidth } from '@aglyn/besigner';
+/**
+ * Statically evaluates a width-only `@media` query at the given
+ * viewport width. Returns null when the query involves anything beyond
+ * px width conditions and the all/screen media types (color-scheme,
+ * hover, em units…) — such queries must stay live in the browser.
+ * Comma-separated clauses OR together, per the media-query spec.
+ */
+export declare function evaluateWidthMediaQuery(query: string, width: number): boolean | null;
+/**
+ * Returns a copy of an sx value with width-only `@media` slices
+ * resolved at the device width: matching slices inline exactly where
+ * the media key sat (later duplicate keys override earlier ones — the
+ * same order the CSS cascade gives equal-specificity rules), and
+ * off-device slices drop. Non-width media keys pass through untouched,
+ * as do arrays (per-entry) and theme callbacks (wrapped).
+ */
+export declare function resolveSxForDeviceWidth<T>(sx: T, width: number): T;
+type ThemeBreakpoints = Theme['breakpoints'];
+/**
+ * Returns breakpoint helpers whose queries are forced for the given
+ * width: helpers whose real media query would match a `width`-wide
+ * viewport emit an always-true query (a sub-pixel min-width), the rest
+ * emit a never-true one (an unreachable min-width). Each helper/key
+ * pair gets a distinct slot number so forced queries never collide
+ * into one style-object key. `values`/`keys`/`unit` stay real —
+ * components (e.g. MuiContainer) read them as pixel numbers.
+ *
+ * `internal_mediaKeys` is rebuilt from the pinned `up()` outputs so
+ * MUI's style engine pre-seeds them in ascending-breakpoint order —
+ * responsive sx slices keep mobile-first cascade order no matter what
+ * order they were authored in.
+ */
+export declare function pinBreakpointsToWidth(breakpoints: ThemeBreakpoints, width: number): ThemeBreakpoints;
+/**
+ * A canvas-only clone of the site theme pinned to the device width:
+ * breakpoint helpers are forced (see {@link pinBreakpointsToWidth}) and
+ * the toolbar mixin — whose real viewport queries were baked in at
+ * createTheme time — is rebuilt against them. The dense xs-landscape
+ * (48px) toolbar rule is intentionally omitted: device previews
+ * simulate portrait-first widths, and that rule only exists for real
+ * rotated phones.
+ */
+export declare function createDevicePinnedTheme(theme: Theme, width: number): Theme;