efficient-easel 0.0.0 → 0.97.0

package/dist/gold/index.d.ts

@@ -0,0 +1,280 @@
+import * as react from 'react';
+import { Ref } from 'react';
+import { InlineRule, InlineKind } from '../markup/index.js';
+
+/**
+ * The type-in-place box: a controlled leaf, and NOTHING else.
+ *
+ * It holds no string of its own, knows no document, and performs no write. The
+ * host owns the value and decides what a commit means — which is what lets the
+ * same component serve the storefront editor and the campaign designer without
+ * either one leaking into it.
+ */
+interface GoldTextInputProps {
+    /** The authored string, delimiters and all. The single source of truth. */
+    value: string;
+    /**
+     * Every keystroke. The layer repaints from what the host sends back, so a host
+     * that drops this on the floor gets a box that does not type — deliberately:
+     * one value, one owner.
+     */
+    onInput: (value: string) => void;
+    /**
+     * The edit is finished and may be written: on blur, and on Enter when
+     * {@link multiline} is false. Fires ONCE per editing session, and never at all
+     * if nothing was typed — clicking into a part and back out must not dirty the
+     * page (owner ruling 6), and one session is one undo step (ruling 2).
+     */
+    onCommit?: (value: string) => void;
+    /**
+     * Escape. The argument is the value the component was given when it gained
+     * focus; the HOST puts it back, because the host owns the string. After a
+     * cancel the pending edit is forgotten, so the blur that follows writes
+     * nothing.
+     */
+    onCancel?: (restored: string) => void;
+    /**
+     * What Enter means — NOT how the text wraps. Both modes soft-wrap exactly as
+     * the box does, because the layer under it has to wrap identically.
+     *
+     *   - `false` (default): Enter commits and never inserts a newline;
+     *   - `true`: Enter inserts a newline and commits nothing.
+     */
+    multiline?: boolean;
+    /** Shown while the value is empty — through the first focus, and away on the
+     *  first keystroke. */
+    placeholder?: string;
+    /** Extra class(es) merged onto the wrapper. */
+    className?: string;
+    /**
+     * The grammar's rule set — `STOREFRONT_MARKUP` in the shop,
+     * `CAMPAIGN_MARKUP` in the campaign designer, both from
+     * `efficient-easel/markup`. Defaults to `STANDARD_MARKUP`, which is the subset
+     * every product shares; a product with legacy runs (the storefront's
+     * `*phrase*` accent) MUST pass its own set or those runs draw as plain text
+     * here while the page paints them gold.
+     */
+    rules?: readonly InlineRule[];
+    /** Accessible name for the box. In-place editing has no visible label. */
+    ariaLabel?: string;
+    /**
+     * Nothing may be typed. The box goes out of the tab order and announces the
+     * state itself, rather than a parent dimming a control that is still
+     * focusable — the regression the 2026-08-06 audit closed.
+     *
+     * The LAYER still paints, deliberately: a sent campaign opens read-only, and
+     * a merchant reading it should see their own formatting, not raw delimiters.
+     */
+    disabled?: boolean;
+    /**
+     * A handle on the textarea.
+     *
+     * A plain prop rather than `ref`, for the same reason {@link GoldLayerProps}
+     * gives for `layerRef`: React 18 would need `forwardRef` and React 19 takes
+     * `ref` as an ordinary prop, and this package supports both.
+     *
+     * It exists because a caret operation — a mark button, an inserted merge tag —
+     * has to read the live selection off this element and put it back after the
+     * repaint. `efficient-easel/copy` is the caller that does that.
+     */
+    inputRef?: Ref<HTMLTextAreaElement>;
+}
+interface GoldLayerProps {
+    value: string;
+    rules?: readonly InlineRule[];
+    className?: string;
+    /**
+     * A handle on the layer element.
+     *
+     * A plain prop rather than `ref` on purpose: React 18 would need
+     * `forwardRef` and React 19 takes `ref` as an ordinary prop, and this package
+     * supports both (`peerDependencies: react >=18`). One named prop behaves
+     * identically on either and needs no version branch.
+     */
+    layerRef?: Ref<HTMLDivElement>;
+}
+
+/**
+ * Type where the text sits, and watch the gold appear as you type.
+ *
+ * The arrangement, in one paragraph: a textarea whose own text is TRANSPARENT
+ * sits on top of a layer holding the same characters, painted. What you read is
+ * the layer; what the caret walks is the box. Both take their type styles from
+ * whatever the host renders them inside (`font: inherit` all the way down), so
+ * the glyphs land on top of each other instead of near each other, and the box
+ * inherits the page's own type rather than a size this package invented.
+ *
+ * The layer is the element IN FLOW and the box is absolutely positioned over it,
+ * which is deliberate: the layer holds the same characters, so it wraps to the
+ * same height, so the box grows as the merchant types without anyone measuring
+ * anything.
+ *
+ * WHAT IT DOES NOT DO: write. It has no document, no section, no Puck, no shop.
+ * `onCommit` says "this edit is finished"; what that means is the host's
+ * business. That is what makes it shareable by both editors (constitution E2)
+ * and testable without any of them.
+ *
+ * No `'use client'` — same reason as the rail: the directive is the HOST's to
+ * place, and both editors' chrome are already client components. Unlike the
+ * rail, though, this leaf has hooks, so it must be rendered inside that client
+ * boundary; a server component can import the module but cannot render it.
+ *
+ * Requires `efficient-easel/gold.css`, imported once from a client entry.
+ */
+declare function GoldTextInput({ value, onInput, onCommit, onCancel, multiline, placeholder, className, rules, ariaLabel, disabled, inputRef, }: GoldTextInputProps): react.JSX.Element;
+
+/**
+ * The formatted text, drawn UNDER the box.
+ *
+ * It is a MARKER layer, not a preview of the page. That distinction is the whole
+ * design, and it is why a bold run here is not drawn at weight 600:
+ *
+ *   the caret, the selection and the line breaks all come from the transparent
+ *   textarea on top, which has ONE font. A heavier or slanted face down here is
+ *   wider, so a marked line would wrap a word earlier than the box does and
+ *   every line after it would sit on top of the wrong text.
+ *
+ * So the layer may only paint what cannot move a glyph — colour, opacity,
+ * text-decoration, a shadow. A merchant sees WHERE the formatting starts and
+ * ends and in which colour it will land; the real weight and slant appear on the
+ * page the moment they click away. Full WYSIWYG (asterisks gone, real faces) is
+ * a second text engine and is deliberately out of scope — see CLAUDE.md.
+ *
+ * The elements mirror the storefront's own renderer (`goldPhrases.tsx`):
+ * `<strong>` for bold, `<em>` for italic and for the gold accent, `<s>` for
+ * struck-out. The classes carry the paint; the tokens carry the values.
+ */
+declare function GoldLayer({ value, rules, className, layerRef }: GoldLayerProps): react.JSX.Element;
+
+/**
+ * Cutting an authored string into the pieces the layer paints — WITHOUT losing a
+ * character.
+ *
+ * The grammar is not re-implemented here and never will be (constitution E8):
+ * {@link tokenizeInline} from `efficient-easel/markup` (../markup) decides what is a run and
+ * what is not, exactly as it does for the published page. What it does not
+ * return is the delimiters — it hands back a run's INNER text, because every
+ * other consumer wants the words without the asterisks.
+ *
+ * This layer wants the asterisks. It draws underneath a transparent box whose
+ * caret walks the stored string, so the two surfaces must hold the same
+ * characters in the same order: drop the `**` and every glyph after it sits two
+ * columns left of the caret that is supposed to be inside it.
+ *
+ * So each parsed run is located back in the source and cut into three pieces —
+ * opening delimiter, inner text, closing delimiter — and EVERY piece is sliced
+ * out of the original string rather than rebuilt from the token. Nothing is
+ * retyped, so nothing can be retyped wrong.
+ */
+/** A piece of the source: a parsed run's kind, or the delimiters around one. */
+type GoldSegmentKind = InlineKind | 'delimiter';
+interface GoldSegment {
+    kind: GoldSegmentKind;
+    /** Verbatim source text. Concatenating every segment reproduces the input. */
+    text: string;
+}
+/**
+ * Split `value` into paint-able segments under `rules`.
+ *
+ * GUARANTEE: `segments.map(s => s.text).join('') === value`, always. If the walk
+ * below cannot line a run up with the rule that produced it — which would mean
+ * the grammar and this function disagree — the whole string comes back as one
+ * plain `text` segment. Losing the gold is a disappointment; losing a character
+ * puts the caret in the wrong place, so the fallback is never in doubt.
+ */
+declare function goldSegments(value: string, rules: readonly InlineRule[]): GoldSegment[];
+
+/**
+ * Gold-layer paint tokens.
+ *
+ * SHORT LIST BY DESIGN. The layer draws inside whatever the host renders it in
+ * and inherits that context's type entirely — family, size, weight, line-height,
+ * letter-spacing — because it has to sit on top of a box that inherits the same
+ * (see `GoldTextInput`). So there is no type here to tokenise; what is left is
+ * the paint, and only the paint that cannot move a glyph.
+ *
+ * NOTHING HERE IS INVENTED (CLAUDE.md — "the tokens are not ours to invent"):
+ *   - the gold defers to the page's own `--gold`, falling back to the
+ *     storefront's light-theme value (`efficient-shop/app/globals.css` → `--gold:
+ *     #c9a461`), so the mark in the box matches the mark on the page;
+ *   - the caret and the placeholder defer to the shell layer's `--es-text` /
+ *     `--es-field-placeholder` (see `shell/tokens.ts`) with the same values as
+ *     their fallbacks;
+ *   - the FOCUSED dim is the rail's existing disabled opacity (0.35), not a new
+ *     number. Its RESTING sibling (0.25) is the one value in this file picked by
+ *     eye rather than borrowed: nothing else in the product paints a mark that
+ *     has to hold its width while it stops being read, so there was nothing to
+ *     copy. The owner chose it against a picker rendering the candidates at
+ *     heading and body size; 0.18 was tried there first and still read too
+ *     faint (card 8807). That history is here on purpose: a later reader who
+ *     finds 0.25 with nothing behind it will "fix" it to match some other
+ *     number, and this is the paragraph that stops them.
+ *
+ * Every value is a STRING, unlike the rail's and shell's pixel magnitudes:
+ * none of these is a length, so nothing here gains a unit on the way into CSS.
+ *
+ * Exposed BOTH ways, per the same value: `goldTokens` (this object) and
+ * `gold.css` (the stylesheet, which declares them on `.es-gold` — names in
+ * {@link goldCssVars}). The parity gate in `tests/gold-leaf-safety.test.ts`
+ * proves the two never drift.
+ */
+declare const goldTokens: {
+    /** The mark colour — `==phrase==` and the legacy `*phrase*`. */
+    readonly accent: "var(--gold, #c9a461)";
+    /** Quiet — `^^phrase^^`. Colour only: the page draws it smaller, but a
+     *  smaller glyph down here would pull the layer off the caret. */
+    readonly quiet: "var(--es-muted, #6b7280)";
+    /** The caret. Set explicitly because the box's own text is transparent, and
+     *  `caret-color: auto` would make the caret transparent with it. */
+    readonly caret: "var(--es-text, #111827)";
+    /** The hint shown while the value is empty. */
+    readonly placeholder: "var(--es-field-placeholder, #9ca3af)";
+    /** How far the asterisks are dimmed WHILE THE BOX HAS FOCUS — the moment they
+     *  are what the merchant is aiming at, so this is the louder of the pair.
+     *  Out of focus they drop to {@link goldTokens.delimiterRestingOpacity}. */
+    readonly delimiterOpacity: "0.35";
+    /** How far they are dimmed AT REST, when nobody is typing (card 8807). A
+     *  whisper, and deliberately not 0.
+     *
+     *  FADED, never removed: the characters stay in the layer at their full width
+     *  in BOTH states, which is the deal — anything that took them out would move
+     *  a glyph. So the width is spent either way, and 0 spends it with nothing to
+     *  show for it: a short, heavily marked string loses about a quarter of its
+     *  line to blanks that read as a rendering bug. Faint, the same space reads as
+     *  punctuation. */
+    readonly delimiterRestingOpacity: "0.25";
+    /**
+     * Faux-bold. A real `font-weight: 600` is wider, and a wider run down here
+     * wraps a line earlier than the transparent box on top of it — after which
+     * every following line is drawn over the wrong text. The shadow reads heavier
+     * and moves nothing.
+     */
+    readonly boldShadow: "0 0 0.4px currentColor";
+    /** Italic, marked rather than slanted — an italic FACE has its own widths, and
+     *  the layer may not change a glyph's advance. Same reason as the bold. */
+    readonly italicDecoration: "underline dotted";
+    /** Strike-through is metric-safe, so it is drawn exactly as it will print. */
+    readonly strikeDecoration: "line-through";
+    /**
+     * The field's inner inset, applied to the LAYER, the BOX and the
+     * PLACEHOLDER together — never to the wrapper.
+     *
+     * ⚠️ ZERO IS THE ONLY SAFE DEFAULT AND A HOST MUST NOT PAD `.es-gold`.
+     * The box is `position: absolute; inset: 0`, which resolves to the
+     * wrapper's PADDING box, while the layer is in flow and starts at its
+     * CONTENT box — so padding the wrapper moves the glyphs and leaves the
+     * caret behind. That shipped: `.es-copy-box` padded the wrapper and every
+     * character sat 6px right of its caret and 4px down (reported 2026-09-26).
+     * A host that wants an inset sets this token.
+     */
+    readonly pad: "0";
+};
+type GoldTokens = typeof goldTokens;
+/**
+ * The CSS custom-property name behind each token. `gold.css` sets these on
+ * `.es-gold`, so overriding one on (or above) the box re-themes it without
+ * shipping new CSS — e.g. `style={{ ['--es-gold-accent']: brand }}`.
+ */
+declare const goldCssVars: Record<keyof GoldTokens, string>;
+
+export { GoldLayer, type GoldLayerProps, type GoldSegment, type GoldSegmentKind, GoldTextInput, type GoldTextInputProps, type GoldTokens, goldCssVars, goldSegments, goldTokens };

package/dist/gold/index.js

@@ -0,0 +1 @@
+export{GoldLayer,GoldTextInput,goldSegments}from"../chunk-CERTFXCV.js";import"../chunk-6OPSJGAI.js";var e={accent:"var(--gold, #c9a461)",quiet:"var(--es-muted, #6b7280)",caret:"var(--es-text, #111827)",placeholder:"var(--es-field-placeholder, #9ca3af)",delimiterOpacity:"0.35",delimiterRestingOpacity:"0.25",boldShadow:"0 0 0.4px currentColor",italicDecoration:"underline dotted",strikeDecoration:"line-through",pad:"0"},t={accent:"--es-gold-accent",quiet:"--es-gold-quiet",caret:"--es-gold-caret",placeholder:"--es-gold-placeholder",delimiterOpacity:"--es-gold-delim-opacity",delimiterRestingOpacity:"--es-gold-delim-resting-opacity",boldShadow:"--es-gold-bold-shadow",italicDecoration:"--es-gold-italic-decoration",strikeDecoration:"--es-gold-strike-decoration",pad:"--es-gold-pad"};export{t as goldCssVars,e as goldTokens};