@formicoidea/labre-framework-uml 0.42.0

package/dist/component.d.ts

@@ -0,0 +1,521 @@
+import type { UmlNodeKind } from '@formicoidea/labre-core/model';
+import { type UmlRoleId } from './roles.js';
+/**
+ * A UML component — the SHAPE and its own words, grouped.
+ *
+ * ## Why a UML artefact is several elements
+ *
+ * UML 2.5.1 draws a classifier as a rectangle divided into COMPARTMENTS
+ * (§9.2.4, §11.4.4): the name on top, the attributes under a line, the
+ * operations under a second one. Those compartments are not decoration — they
+ * are three separate statements about the same classifier, and an author edits
+ * them one at a time.
+ *
+ * The library already knows how to draw that: the same arrangement C4 arrived
+ * at through the PO's recette of 28/08/2026 (`gfx/c4/src/component.ts`), which
+ * R15/R16 then generalised into a rule. A component is a native `group` holding
+ * a `umlNode` shape that carries NO inner text and one canvas `text` element per
+ * compartment, each stamped with its own role. One click selects the classifier,
+ * a second descends into the compartment under the pointer, and every gesture
+ * the editor already has works on it.
+ *
+ * ## This module
+ *
+ * The two questions that arrangement raises, both PURE and both free of `std`
+ * and of Yjs, so the creation site, the node renderer, the exporter and a test
+ * all answer them the same way:
+ *
+ *  - **where do the compartments go**, given a node's box
+ *    ({@link umlCompartmentBoxes}) — and, as a by-product nobody else can
+ *    compute, WHERE THE SEPARATORS ARE, which is what the renderer strokes;
+ *  - **which words belong to which shape**, given a group and a flat element
+ *    list ({@link umlComponentSiblings}) — resolved by group membership plus the
+ *    role stamped on each text, never by position in `children`.
+ *
+ * The role stays on the SHAPE and on each text; the group carries none
+ * (`roles.ts`).
+ */
+/**
+ * The gap between a compartment's words and the line that closes it, and
+ * between the words and the outline of the box.
+ *
+ * One number for the top, the bottom and — through {@link UML_TIER_SIDE_INSET}
+ * — the sides, because UML draws one: the specification's figures are typeset
+ * with a single uniform padding inside every compartment, and a second value
+ * would read as a distinction between compartments that the notation never
+ * makes.
+ */
+export declare const UML_TIER_MARGIN = 8;
+/**
+ * The side padding, as a FRACTION of the box width rather than the absolute
+ * {@link UML_TIER_MARGIN}.
+ *
+ * A UML box is resized far more often horizontally than vertically — an author
+ * widens a class to fit `+ findByCustomerId(id : CustomerId) : Order`, they do
+ * not make it taller to fit a longer word. A proportional inset keeps the text
+ * column looking deliberate at every width; an absolute one would leave a
+ * 200-unit box looking padded and a 600-unit box looking unpadded.
+ */
+export declare const UML_TIER_SIDE_INSET = 0.08;
+/**
+ * Line height, as a multiple of the font size — the one number that turns
+ * "three lines of attributes" into a height.
+ */
+export declare const UML_TIER_LINE_HEIGHT = 1.4;
+/**
+ * The gap between the NAME and the line under it.
+ *
+ * Smaller than {@link UML_TIER_MARGIN} on purpose: the name compartment of a
+ * fresh classifier holds one line and, for an interface or an enumeration, a
+ * keyword line above it (§9.5.4 — `«interface»`), and that pair has to read as
+ * one heading rather than as a block floating in an over-tall compartment.
+ */
+export declare const UML_NAME_GAP = 6;
+/**
+ * How many lines the ATTRIBUTES compartment is sized for.
+ *
+ * Three, because that is what a default 200 × 120 box leaves room for once the
+ * name compartment and the margins are taken out, and because a classifier with
+ * three attributes and one or two operations is the shape of nearly every class
+ * anybody draws first. The operations compartment takes whatever is left, which
+ * is the one tier that must never be sized in lines: it is the bottom of the
+ * box, and a box an author has dragged taller has dragged it taller FOR the
+ * operations.
+ *
+ * Since the compartment watcher this is the DEFAULT rather than the sizing: a
+ * caller that has read the tier passes its real line count
+ * ({@link UmlTierLines}), and three is what a caller who has not read it gets —
+ * the stencil's own shape, which is every classifier's until somebody types.
+ */
+export declare const UML_ATTRIBUTE_LINES = 3;
+/**
+ * The share of a `package` box its TAB occupies, top-left (§12.2.4).
+ *
+ * A fraction rather than an absolute, because the tab is part of the DRAWING:
+ * a package dragged to twice the height is the same folder, twice as big, and a
+ * tab pinned to 26 units would turn into a sliver. Exported so the node
+ * renderer strokes the tab exactly where the name compartment stops, rather
+ * than the two agreeing by coincidence.
+ */
+export declare const UML_PACKAGE_TAB = 0.2;
+/**
+ * The share of an `actor` box the STICK FIGURE occupies, measured from the top
+ * (§18.1.4 — the figure, and its name written underneath it).
+ *
+ * Exported for the same reason as {@link UML_PACKAGE_TAB}: the renderer draws
+ * the figure ABOVE this line and {@link umlCompartmentBoxes} puts the name
+ * BELOW it, and a head overlapping its own label is what happens when two files
+ * each pick their own number.
+ */
+export declare const UML_ACTOR_FIGURE = 0.74;
+/**
+ * The DEPTH of the 3-D cube a node, a device and an execution environment are
+ * drawn as (§19.4.4), as a fraction of the box's shorter side.
+ *
+ * A fraction of the SHORTER side rather than of the width, because the depth is
+ * drawn at 45° in both directions: taking it from the width alone would make a
+ * cube dragged wide and flat lose its top face off the top of the element.
+ *
+ * Exported for the reason {@link UML_PACKAGE_TAB} is: the renderer draws the
+ * three faces from this number and {@link umlCompartmentBoxes} writes the name
+ * INSIDE the front one, so a name floating over the cube's roof is what happens
+ * when two files each pick their own depth. 12% is the proportion §19.4.4's own
+ * figures show — enough to read as a solid, little enough to leave the front
+ * face the size of a box.
+ */
+export declare const UML_CUBE_DEPTH = 0.12;
+/**
+ * The gap between a glyph too small to write in and the name written BESIDE it.
+ *
+ * Three kinds are in that position, and all three by the notation's own doing: a
+ * port is a small square on a border (§11.3.4), and the ball and socket of
+ * §10.4.4 are a curve on a stub. None of them has an inside, so the label goes
+ * next to the picture — which is exactly how the specification's figures write
+ * them.
+ */
+export declare const UML_BESIDE_LABEL_GAP = 6;
+/**
+ * How wide that label is allowed to be before it wraps.
+ *
+ * An absolute rather than a fraction, unlike every other measurement here,
+ * because it is measuring the WORDS and not the glyph: a port dragged twice as
+ * big is a bigger square with the same name beside it, and a name column scaled
+ * to a 16-unit square would be four characters wide.
+ */
+export declare const UML_BESIDE_LABEL_WIDTH = 120;
+/**
+ * How deep the POINT of a signal pentagon bites into its box (§16.3.4), as a
+ * fraction of the width.
+ *
+ * Exported for the reason {@link UML_PACKAGE_TAB} is: the renderer draws the
+ * pentagon from this number and {@link umlCompartmentBoxes} pulls the label box
+ * back out of the point by it, so a signal's name cannot end up running out
+ * through the tip. One number, two readers.
+ *
+ * The same depth for both shapes, because §16.3.4 draws the same pentagon twice
+ * and merely turns it: a send signal's point sticks OUT of the right edge, an
+ * accept event's bites IN from the left, and a reader tells them apart by which
+ * way the arrow of the silhouette runs. Two depths would make the pair look like
+ * two unrelated shapes.
+ */
+export declare const UML_SIGNAL_POINT = 0.16;
+/** A box in the same units and origin as the node's own. */
+export interface UmlBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * The written compartments of one node, plus the separators between them.
+ *
+ * `attributes` and `operations` are optional because most of the pack has
+ * neither: a package, a note, an actor and a use case carry ONE label and no
+ * compartment at all (§12.2.4, §18.1.4, Annex A), and an object carries a name
+ * and its slots but no operations (§9.8.4 — an instance has values, not
+ * behaviour).
+ *
+ * `splits` are offsets DOWN FROM THE TOP of the node's box, in model units, and
+ * they are the renderer's whole instruction: stroke a full-width line at each.
+ * They are returned from here rather than recomputed there because they are not
+ * a second fact — a separator IS the boundary between two compartments, and two
+ * files deriving it separately is how a line ends up crossing the words it was
+ * supposed to sit under.
+ */
+export interface UmlCompartmentBoxes {
+    name: UmlBox;
+    attributes?: UmlBox;
+    operations?: UmlBox;
+    splits: number[];
+}
+/**
+ * How many LINES each compartment actually holds — the one thing a box cannot
+ * tell you.
+ *
+ * {@link umlCompartmentBoxes} is otherwise a pure function of a rectangle, and
+ * that was enough for as long as every classifier was assumed to hold the
+ * stencil it was born with: one name line, three attributes, and the operations
+ * taking the rest. An author who types five attributes into the second tier has
+ * overflowed it — the words run through the separator under them and out the
+ * bottom of the box — and nothing in a rectangle says so.
+ *
+ * So the counts are passed IN, from whoever has read the tiers
+ * ({@link umlTierLineCount}), and every field is optional: a caller that knows
+ * nothing about the words gets exactly the layout this module has always
+ * returned. `UmlCompartmentWatcher` is what supplies them after an edit
+ * commits, and the node renderer is what keeps the separators where the tiers
+ * then are.
+ *
+ * `operations` is read by {@link umlStackHeight} and NOT by
+ * {@link umlCompartmentBoxes}, and that asymmetry is the notation's: the
+ * operations compartment is the bottom of the box and always takes whatever is
+ * left (§11.4.4), so its line count says how tall the box must BE, never how
+ * tall the compartment is drawn.
+ */
+export interface UmlTierLines {
+    name?: number;
+    attributes?: number;
+    operations?: number;
+}
+/**
+ * How many lines one LOGICAL line of a tier is painted as — the measurement
+ * this module cannot make and {@link umlTierLineCount} therefore takes.
+ *
+ * A canvas text element is drawn WRAPPED: the renderer breaks each line at the
+ * element's own width before it paints it (`gfx/text`'s `wrapText`), so
+ * `+ findByCustomerIdAndStatus(id : CustomerId) : List<Order>` in a 168-unit
+ * compartment is one line in the document and three on the picture. Answering
+ * that needs a font context — a `getFontString` and a canvas measurer — which
+ * this module (pure, free of `std` and of the DOM) has none of, so the caller
+ * that HAS one passes the answer in.
+ */
+export type UmlTierWrap = (line: string) => number;
+/**
+ * How many lines a tier's text is PAINTED as.
+ *
+ * Takes the VALUE rather than the element, for the reason {@link umlTierText}
+ * does — a `Y.Text` on a model, a string in a fixture. The author's newlines are
+ * counted always; `wrap` adds the ones the renderer makes, and without it the
+ * count is the newlines alone.
+ *
+ * ## Why `wrap` is not optional in practice
+ *
+ * It was, until the PO's recette of 14/09/2026. A tier is created with
+ * `hasMaxWidth`, so the text editor wraps a long signature at the compartment's
+ * width and grows the box downward while the author types — and the watcher then
+ * SHRANK that box back to one line's worth on commit, painting the wrapped
+ * remainder straight through the separator under it. Measured on a 200-unit
+ * class: three typed attribute lines, six painted, a 92.7-unit stack put back
+ * into a 54.6-unit compartment.
+ *
+ * So every caller that can measure must: `umlFitComponent` does, through
+ * `umlTierWrapper` (`node/tier-metrics.ts`), and the `wrap`-less form is what a
+ * fixture and a pure test get.
+ *
+ * An empty tier is one line, which is `\n`-count + 1 and also what §14.2.4
+ * wants: a state's behaviour compartment is seeded EMPTY and is still ruled off.
+ */
+export declare function umlTierLineCount(text: unknown, wrap?: UmlTierWrap): number;
+/**
+ * The three glyphs with no INSIDE, whose name is therefore written next to them
+ * — outside the element's own box, which nothing else in this module does.
+ *
+ * Exported because that is a fact a caller has to know: a port's label is the
+ * one tier that makes the GROUP bigger than the shape it belongs to, and a test
+ * or a layout asserting "every tier is inside its node" has to say which three
+ * kinds the notation exempts (§11.3.4, §10.4.4).
+ */
+export declare const UML_BESIDE_LABEL_KINDS: ReadonlySet<UmlNodeKind>;
+/**
+ * The kinds whose one tier is written in a HEAD drawn wider than the element
+ * itself — today the lifeline, and it is the second and last way a tier is
+ * allowed outside its own box.
+ *
+ * ## Why a lifeline is shaped like this at all
+ *
+ * §17.2.4 draws a lifeline as a NAMED BOX with a dashed line falling out of the
+ * bottom of it, and the dashed line is the part that matters: a message is
+ * attached to it at the height where it happens, and an execution bar sits on
+ * it. So the ELEMENT is the spine — a narrow, tall column whose left and right
+ * perimeters are where the connector layer puts an anchor — and the head is a
+ * rectangle the renderer draws across the top of it, centred, overflowing it by
+ * the same amount on each side (`consts.ts`, `UML_LIFELINE_HEAD`).
+ *
+ * That makes the head the one place the participant's name can go. Writing it
+ * inside a 16-unit column would be writing it on the dashes.
+ *
+ * ## Why it is not {@link UML_BESIDE_LABEL_KINDS}
+ *
+ * Because it is not beside anything: a port's name sits to the RIGHT of a glyph
+ * that has no inside, and a lifeline's name sits IN a head the renderer draws.
+ * The two would share nothing but the fact that a bounding box has to allow for
+ * them, and folding them together would give a lifeline a label floating 6
+ * units off the spine. Two sets, two placements, one invariant each.
+ */
+export declare const UML_HEAD_LABEL_KINDS: ReadonlySet<UmlNodeKind>;
+/**
+ * WHICH tier role a kind's single word carries, for every kind whose word is a
+ * label rather than a name compartment.
+ *
+ * The companion of {@link glyphLabel}: that answers where the one tier GOES,
+ * this answers what it IS, and the two questions have had the same shape since
+ * the lifeline arrived — a placement chosen per kind and a role chosen per
+ * kind, which is exactly one table each.
+ *
+ * Today it says one thing: a lifeline's head carries `uml:lifeline-ident` and
+ * everything else carries `uml:label`. §17.3.4 prints a BNF for what goes in
+ * that head (`parseLifelineIdent` reads it back) and §18.1.4 prints none for an
+ * actor's word, so the two tiers answer "does this parse" differently and a
+ * single role could only ever have asked them the same question (`roles.ts`).
+ *
+ * It does NOT answer for the compartmented kinds or for the five glyphs named
+ * rather than labelled (`actions.ts`, `NAMED_GLYPHS`): those carry `uml:name`,
+ * which is a different statement — a tier a keyword may be written over — and a
+ * helper that folded all three answers together would be a second place to
+ * decide what the grammar reads.
+ */
+export declare function umlLabelRoleOf(kind: UmlNodeKind): UmlRoleId;
+/**
+ * The compartments of a node, laid out against its own box.
+ *
+ * ## The rhythm of a classifier
+ *
+ * A margin, the name over one line, a small gap, THE LINE, three lines of
+ * attributes, THE SECOND LINE, and the operations take the rest down to the
+ * bottom margin. Which is exactly what a 200 × 120 box is tall enough for,
+ * because the box was derived from this stack (`consts.ts`) rather than the
+ * stack fitted into the box — so a fresh class is neither cramped nor half
+ * empty.
+ *
+ * The tiers are stacked by walking DOWN, each placed under the last, rather
+ * than by six independent offsets: six offsets is six chances for two
+ * compartments to overlap, and a walk cannot produce one.
+ *
+ * An `object` walks the same path and stops one tier early: §9.8.4 draws an
+ * instance specification as a name compartment over a SLOT compartment, and
+ * there is no third. So it gets one split, not two, and the slots take the rest
+ * of the box — the tier an author of an object diagram actually types in. A
+ * `component` (§11.6.4) and an `artifact` (§19.3.4) walk exactly the same path,
+ * for exactly the same reason: a name over one body tier.
+ *
+ * ## The ones that are not boxes
+ *
+ * A package, a note, an actor, a use case, the three cubes and the three
+ * interface glyphs are SHAPES the notation draws, not rectangles it divides, so
+ * each returns a single label box positioned against its own picture and no
+ * splits at all:
+ *
+ *  - **package** — under the tab, centred in the body (§12.2.4);
+ *  - **note** — the inner rectangle, top-aligned and read left, because a note
+ *    holds a sentence rather than a title (Annex A);
+ *  - **actor** — under the stick figure, which is where §18.1.4 writes it;
+ *  - **use case** — centred in the ellipse, the only shape with no corner to
+ *    hang a label in;
+ *  - **node / device / execution-environment** — inside the cube's FRONT FACE,
+ *    the only one of its three faces that is not drawn at an angle (§19.4.4);
+ *  - **port / provided-interface / required-interface / time-event** — BESIDE
+ *    the glyph, and outside the element's own box: a small square, a ball on a
+ *    stick and a 40-unit hourglass have no inside to write in (§11.3.4,
+ *    §10.4.4, §16.10.4). The one place this module returns a tier that is not
+ *    contained by the node it belongs to, and
+ *    {@link UML_BESIDE_LABEL_KINDS} is how it says so out loud;
+ *  - **action / object-node** — centred in the box, which is where §15.3.4 and
+ *    §15.4.4 write a verb phrase and a value's name;
+ *  - **send-signal / accept-event** — centred too, but pulled back out of the
+ *    pentagon's POINT by {@link UML_SIGNAL_POINT}, so the words never run out
+ *    through the tip (§16.3.4).
+ *
+ * ## The ones with no words at all
+ *
+ * The control nodes of §15.3.4 and the pseudostates of §14.2.4 are MARKS — a
+ * disc, a bar, a bullseye, a cross — and carry no tier. They still get a box
+ * back from here, centred, because a box is always computable from a box and a
+ * second return shape would cost every caller a branch. What decides whether a
+ * text element is ever created is `UML_UNLABELLED_KINDS` in `keywords.ts`, and
+ * that is the one authority on the question.
+ *
+ * ## What this is not
+ *
+ * A creation-time answer, a render-time one and a commit-time one, and nothing
+ * more. The compartments are real elements from the moment they are drawn: an
+ * author who moves one has moved it, and nothing here runs on its own to put it
+ * back. The margins are absolutes, so a node dragged taller keeps them where
+ * they were and gives the extra height to the tier that takes "the rest".
+ *
+ * The commit-time caller is `UmlCompartmentWatcher` (`node/`), and it is the
+ * one that passes `lines`: when an edit into a tier commits, it re-asks this
+ * function where the compartments go now that the second one holds five lines
+ * instead of three, grows the node if the answer no longer fits
+ * ({@link umlStackHeight}) and writes the tiers to the boxes it gets back. It
+ * is still not a layout engine — nothing runs between keystrokes, and nothing
+ * reclaims height an author has dragged out.
+ */
+export declare function umlCompartmentBoxes(kind: UmlNodeKind, x: number, y: number, w: number, h: number, lines?: UmlTierLines): UmlCompartmentBoxes;
+/**
+ * How tall the node has to BE for the words its tiers hold to fit — `null` for
+ * a kind that has no stack.
+ *
+ * The same walk as {@link umlCompartmentBoxes}, read the other way round: that
+ * function is given a box and hands back where the compartments go, this one is
+ * given the compartments and hands back the box they need. Both are here so
+ * they cannot disagree, which is the whole reason the separators were computed
+ * in this module in the first place.
+ *
+ * The last tier is the one difference between the two. `umlCompartmentBoxes`
+ * gives the operations compartment (or a one-split kind's body) EVERYTHING left
+ * down to the bottom margin, because a box an author has dragged taller has
+ * dragged it taller for them; this returns the height at which "everything
+ * left" is exactly the lines it holds, which is the smallest box that fits.
+ *
+ * `null` rather than a number for a package, an actor, a cube or a mark: those
+ * are pictures the notation draws, not rectangles it divides, and there is no
+ * honest answer to "how tall must this be" for a stick figure. It doubles as
+ * the predicate — a caller that gets a number is looking at a divided box.
+ */
+export declare function umlStackHeight(kind: UmlNodeKind, lines: UmlTierLines): number | null;
+/**
+ * The little a resolution needs to know about an element — an id, a role, and
+ * whatever it says.
+ *
+ * `text` is `unknown` because on a real element it is a `Y.Text` and in a test
+ * it is a string, and this module has no business knowing which: it is read
+ * through {@link umlTierText}, which stringifies whatever it is given. That is
+ * also what keeps this file free of a Yjs import.
+ */
+export interface UmlComponentElement {
+    id: string;
+    role?: string;
+    text?: unknown;
+}
+/** The little a resolution needs to know about a group. */
+export interface UmlComponentGroup {
+    id: string;
+    childIds: readonly string[];
+}
+/**
+ * One classifier's shape and its written compartments, resolved.
+ *
+ * Every field is optional, and that is the honest answer rather than a
+ * defensive one: a group whose texts were deleted, one whose shape was deleted,
+ * and a group an author made out of two unrelated boxes all exist, and none of
+ * them is an error. What a caller does with a missing tier — write nothing,
+ * fall back to the shape's own inner text — is the caller's decision, and the
+ * exporter and the node view make different ones.
+ */
+export interface UmlComponent {
+    node?: UmlComponentElement;
+    name?: UmlComponentElement;
+    attributes?: UmlComponentElement;
+    operations?: UmlComponentElement;
+    label?: UmlComponentElement;
+    /**
+     * §17.3.4's lifeline head — a fifth slot rather than a fifth user of
+     * {@link UmlComponent.label}, for the reason `roles.ts` splits the tier: what
+     * is written here is a production with a grammar, and what is written in a
+     * label is prose. A caller that wants "the word this artefact goes by",
+     * whatever tier holds it, asks for `name ?? label ?? ident` — three tiers,
+     * never both.
+     */
+    ident?: UmlComponentElement;
+}
+/**
+ * Everything one group holds, sorted into the shape and its tiers.
+ *
+ * ## Group membership, then roles
+ *
+ * The group answers "which words are THIS classifier's" — two classes side by
+ * side both carry a `+ attribute : Type`, and only the grouping says which is
+ * which. The role then answers "which of these words is the operations
+ * compartment", which position in `children` cannot: a group's child order is
+ * an implementation detail that a reorder, a copy or a regroup rewrites, while
+ * a role is written on the element and travels with it.
+ *
+ * ## `name` and `label` are two fields, not one
+ *
+ * Because they are two roles, and the vocabulary means them differently: a
+ * `uml:name` is the name of a CLASSIFIER, parsed by the grammar for keywords in
+ * guillemets and for an abstract name in italics (§9.5.4); a `uml:label` is the
+ * plain text of an actor or a use case, which is a name and nothing else. An
+ * exporter that had to ask "is this the name field or the label field" of one
+ * merged slot would be asking about the element's KIND, which the shape already
+ * states. Keeping them apart costs one field and removes the question.
+ *
+ * The FIRST element of each role wins. A group holding two names is a group
+ * somebody built by hand out of two components, and document order is the same
+ * tie-break the export's geometric attribution uses.
+ */
+export declare function umlComponentSiblings(group: UmlComponentGroup, elements: readonly UmlComponentElement[]): UmlComponent;
+/**
+ * The group an element belongs to — `undefined` when it belongs to none.
+ *
+ * The other direction of the same question, and the one the node view needs:
+ * given the shape somebody has just double-clicked, which group holds the text
+ * to open an editor on? The C4 pack answers it with `c4ComponentSiblings(id,
+ * groups)`; this returns the group itself rather than its id list, because the
+ * next call is always {@link umlComponentSiblings}, which takes exactly that.
+ *
+ * The FIRST group holding the element wins. Groups nest, so a component grouped
+ * again inside a bigger group has two ancestors; document order picks the one
+ * written first, which is the innermost — the one the creation site made.
+ */
+export declare function umlGroupOf(elementId: string, groups: readonly UmlComponentGroup[]): UmlComponentGroup | undefined;
+/**
+ * The shape of a resolved component — its `umlNode`, or `undefined` for a group
+ * that holds none.
+ *
+ * A one-line accessor with a name, rather than `component.node` at eleven call
+ * sites, because the QUESTION is worth spelling: "which box are these words
+ * about". The exporter asks it to read a `kind`, the renderer to read a
+ * geometry, and a rule to read a role.
+ */
+export declare function umlNodeOfComponent(component: UmlComponent): UmlComponentElement | undefined;
+/**
+ * Whatever a tier says, as a plain trimmed string.
+ *
+ * Takes the VALUE rather than the element, because that is what every caller
+ * has: a `Y.Text` off a model, a string off a fixture, `undefined` off a tier
+ * that was never created. Stringifying here is what lets the grammar, the
+ * exporter and the renderer stay free of a Yjs import — a `Y.Text` answers
+ * `toString()` with its content, which is the whole of the coupling.
+ */
+export declare function umlTierText(text: unknown): string;