@north-light/crouter 0.3.192 → 0.3.193

package/dist/pages/comments.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Comment list algebra, shared by every element in the bundle so commenting is one
+ * behaviour and not five near-identical ones.
+ *
+ * The editing model is **one comment per anchor**: an option, a row, a column, a card or a
+ * range holds at most one comment, and re-commenting edits it. The response type still
+ * carries a list with ids, because a `range` anchor on a long document naturally grows
+ * several and the contract should not have to change when it does.
+ *
+ * Every function here is pure over the array it is given — elements hold their own comment
+ * list in local state, replace it with the returned one, and hand the whole response to
+ * `respond()`.
+ */
+import type { Comment, CommentAnchor } from './types.js';
+/** A stable string identity for an anchor, used to find and key comments. */
+export declare function anchorKey(anchor: CommentAnchor): string;
+/** The comment on `anchor`, if the user has left one. */
+export declare function findComment(comments: Comment[], anchor: CommentAnchor): Comment | undefined;
+/**
+ * Write a comment at `anchor`, replacing any comment already there. Empty or whitespace-only
+ * text removes it — clearing the box is how you delete, so the popover never needs a separate
+ * destructive path for "I changed my mind". An edit keeps the existing comment's id, so the
+ * response is stable across retyping.
+ */
+export declare function setComment(comments: Comment[], anchor: CommentAnchor, text: string): Comment[];
+/**
+ * Comment ids are frame-local: the host does not mint them, and nothing downstream keys off
+ * their value — `validatePageResponses` only requires a non-empty string. One counter is
+ * shared by every element in the bundle, so ids are unique across a whole page and stay
+ * legible in a response the human reads.
+ */
+export declare function newCommentId(): string;
+/** A short, human label for what a comment is attached to. */
+export declare function anchorLabel(anchor: CommentAnchor): string;

package/dist/pages/comments.js

@@ -0,0 +1,72 @@
+/**
+ * Comment list algebra, shared by every element in the bundle so commenting is one
+ * behaviour and not five near-identical ones.
+ *
+ * The editing model is **one comment per anchor**: an option, a row, a column, a card or a
+ * range holds at most one comment, and re-commenting edits it. The response type still
+ * carries a list with ids, because a `range` anchor on a long document naturally grows
+ * several and the contract should not have to change when it does.
+ *
+ * Every function here is pure over the array it is given — elements hold their own comment
+ * list in local state, replace it with the returned one, and hand the whole response to
+ * `respond()`.
+ */
+/** A stable string identity for an anchor, used to find and key comments. */
+export function anchorKey(anchor) {
+    switch (anchor.kind) {
+        case 'whole':
+            return 'whole';
+        case 'option':
+            return `option:${anchor.optionId}`;
+        case 'row':
+            return `row:${anchor.rowId}`;
+        case 'column':
+            return `column:${anchor.columnId}`;
+        case 'card':
+            return `card:${anchor.cardId}`;
+        case 'range':
+            return `range:${anchor.start}:${anchor.end}`;
+    }
+}
+/** The comment on `anchor`, if the user has left one. */
+export function findComment(comments, anchor) {
+    const key = anchorKey(anchor);
+    return comments.find((comment) => anchorKey(comment.anchor) === key);
+}
+/**
+ * Write a comment at `anchor`, replacing any comment already there. Empty or whitespace-only
+ * text removes it — clearing the box is how you delete, so the popover never needs a separate
+ * destructive path for "I changed my mind". An edit keeps the existing comment's id, so the
+ * response is stable across retyping.
+ */
+export function setComment(comments, anchor, text) {
+    const key = anchorKey(anchor);
+    const rest = comments.filter((comment) => anchorKey(comment.anchor) !== key);
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return rest;
+    const existing = comments.find((comment) => anchorKey(comment.anchor) === key);
+    return [...rest, { id: existing?.id ?? newCommentId(), anchor, text: trimmed }];
+}
+let counter = 0;
+/**
+ * Comment ids are frame-local: the host does not mint them, and nothing downstream keys off
+ * their value — `validatePageResponses` only requires a non-empty string. One counter is
+ * shared by every element in the bundle, so ids are unique across a whole page and stay
+ * legible in a response the human reads.
+ */
+export function newCommentId() {
+    counter += 1;
+    return `c${counter}`;
+}
+/** A short, human label for what a comment is attached to. */
+export function anchorLabel(anchor) {
+    switch (anchor.kind) {
+        case 'whole':
+            return 'this';
+        case 'range':
+            return `\u201c${anchor.quote}\u201d`;
+        default:
+            return anchorKey(anchor);
+    }
+}

package/dist/pages/elements/cards.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<crtr-cards>` — the choice `options` makes, when each candidate has enough body to
+ * deserve its own surface: a meeting slot, a vendor, a search result.
+ *
+ * This is a port of the agent interaction kit's `cards` component, not a new design. The
+ * selection treatment is the kit's selectable-surface recipe — a hairline surface that
+ * answers the pointer and goes accent-toned once chosen — carrying the kit's selection
+ * control and the kit's comment affordance. Navigation is the kit's classic list grammar
+ * (`j`/`k` move, `x` selects, `c` comments), so a card grid, an option list and a table
+ * are all driven the same way.
+ *
+ * Data arrives one of two ways: inline `cards`, or a `source` the host resolves through
+ * `artifactData()`. The element never touches the network, and anything it cannot render —
+ * a malformed config, an unreachable source, source data that is not a card list — becomes
+ * a named unavailable state rather than an exception.
+ */
+export {};