@fusion.dev/helix-headless 0.199.1 → 0.200.0

package/types/svelte.d.ts

@@ -95,6 +95,9 @@ declare module 'svelte/elements' {
     'helix-headless-list': Helix<'helix-headless-list'>
     'helix-headless-listbox': Helix<'helix-headless-listbox'>
     'helix-headless-loader': Helix<'helix-headless-loader'>
+    'helix-headless-log-group': Helix<'helix-headless-log-group'>
+    'helix-headless-log-line': Helix<'helix-headless-log-line'>
+    'helix-headless-log': Helix<'helix-headless-log'>
     'helix-headless-map-area': Helix<'helix-headless-map-area'>
     'helix-headless-map-buildings': Helix<'helix-headless-map-buildings'>
     'helix-headless-map-contours': Helix<'helix-headless-map-contours'>

package/types/vue.d.ts

@@ -83,6 +83,10 @@ import type {
   HelixHeadlessList,
   HelixHeadlessListbox,
   HelixHeadlessLoader,
+  HelixHeadlessLogGroup,
+  timeOf,
+  HelixHeadlessLogLine,
+  HelixHeadlessLog,
   HelixHeadlessMapArea,
   HelixHeadlessMapBuildings,
   HelixHeadlessMapContours,
@@ -10050,6 +10054,221 @@ progress. */
 
 export type HelixHeadlessLoaderVueEvents = {};
 
+/** `HelixHeadlessLogGroup` component event */
+export type HelixHeadlessLogGroupElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessLogGroup,
+  E
+>;
+/** `helix-before-close` event type */
+export type HelixHeadlessLogGroupHelixBeforeCloseElementEvent =
+  HelixHeadlessLogGroupElementEvent<HelixBeforeCloseEvent>;
+/** `helix-before-open` event type */
+export type HelixHeadlessLogGroupHelixBeforeOpenElementEvent =
+  HelixHeadlessLogGroupElementEvent<HelixBeforeOpenEvent>;
+/** `toggle` event type */
+export type HelixHeadlessLogGroupToggleElementEvent =
+  HelixHeadlessLogGroupElementEvent<ToggleEvent>;
+
+export type HelixHeadlessLogGroupVueProps = {
+  /** How long the step took, as it should read, such as `12s`. */
+  duration?: (HelixHeadlessLogGroup["duration"]) | undefined;
+  /** What the step is called. The `heading` slot replaces it. */
+  heading?: (HelixHeadlessLogGroup["heading"]) | undefined;
+  /** Where the step stands, which draws a mark before the heading. */
+  status?: (HelixHeadlessLogGroup["status"]) | undefined;
+  /** What a screen reader hears for the status, after the heading.
+`{status}` is one of `pending`, `running`, `done`, `failed`, and `skipped`. */
+  "status-label"?: (HelixHeadlessLogGroup["statusLabel"]) | undefined;
+  /** What a screen reader hears for the status, after the heading.
+`{status}` is one of `pending`, `running`, `done`, `failed`, and `skipped`. */
+  statusLabel?: (HelixHeadlessLogGroup["statusLabel"]) | undefined;
+  /** Whether the element starts open. Ignored once `open` is written. */
+  "default-open"?: (HelixHeadlessLogGroup["defaultOpen"]) | undefined;
+  /** Whether the element starts open. Ignored once `open` is written. */
+  defaultOpen?: (HelixHeadlessLogGroup["defaultOpen"]) | undefined;
+  /** Whether the element is open.
+
+One property, not two, so `dialog.open` answers the question anyone
+asking it meant. Writing always applies; `<helix-dialog open>` is the
+same statement in markup.
+
+**Not reflected, and that is required rather than tidy.** Reflection
+writes the resolved state back as an attribute, so an element that opened
+itself would put `open` on its own host: cloned, serialized for
+hydration, or diffed by a framework, it comes back holding whatever the
+last reader did rather than what the author wrote. `:state(open)` carries
+the resolved state for stylesheets, which is what the mirror is for. */
+  open?: (HelixHeadlessLogGroup["open"]) | undefined;
+};
+
+export type HelixHeadlessLogGroupVueEvents = {
+  /** Fired before the group closes. Cancelable. */
+  "helix-before-close": HelixHeadlessLogGroupHelixBeforeCloseElementEvent;
+  /** Fired before the group opens. Cancelable. */
+  "helix-before-open": HelixHeadlessLogGroupHelixBeforeOpenElementEvent;
+  /** Fired after the group opens or closes, with `newState` and `oldState`. */
+  toggle: HelixHeadlessLogGroupToggleElementEvent;
+};
+
+export type HelixHeadlessLogLineVueProps = {
+  /** When the line was written: milliseconds since the epoch, or anything `Date` parses. */
+  at?: (HelixHeadlessLogLine["at"]) | undefined;
+  /** How much the line matters. Absent is `info`. */
+  level?: (HelixHeadlessLogLine["level"]) | undefined;
+  /** What a screen reader hears for the link on a line's number. `{number}` is the number. */
+  "line-label"?: (HelixHeadlessLogLine["lineLabel"]) | undefined;
+  /** What a screen reader hears for the link on a line's number. `{number}` is the number. */
+  lineLabel?: (HelixHeadlessLogLine["lineLabel"]) | undefined;
+};
+
+export type HelixHeadlessLogLineVueEvents = {};
+
+/** `HelixHeadlessLog` component event */
+export type HelixHeadlessLogElementEvent<E = Event> = TypedEvent<
+  HelixHeadlessLog,
+  E
+>;
+/** `helix-before-pin` event type */
+export type HelixHeadlessLogHelixBeforePinElementEvent =
+  HelixHeadlessLogElementEvent<HelixBeforePinEvent>;
+/** `helix-expand` event type */
+export type HelixHeadlessLogHelixExpandElementEvent =
+  HelixHeadlessLogElementEvent<HelixExpandEvent>;
+/** `helix-pin` event type */
+export type HelixHeadlessLogHelixPinElementEvent =
+  HelixHeadlessLogElementEvent<HelixPinEvent>;
+
+export type HelixHeadlessLogVueProps = {
+  /** Whether the log opens following its newest line, when `pinned` is not set.
+`default-pinned="false"` opens it where it starts. */
+  "default-pinned"?: (HelixHeadlessLog["defaultPinned"]) | undefined;
+  /** Whether the log opens following its newest line, when `pinned` is not set.
+`default-pinned="false"` opens it where it starts. */
+  defaultPinned?: (HelixHeadlessLog["defaultPinned"]) | undefined;
+  /** Whether the run is over, which a screen reader is told once.
+
+Set it when output you `write` is complete. A `source` sets it when the
+stream ends. */
+  done?: (HelixHeadlessLog["done"]) | undefined;
+  /** What a screen reader hears when the run is over. */
+  "done-label"?: (HelixHeadlessLog["doneLabel"]) | undefined;
+  /** What a screen reader hears when the run is over. */
+  doneLabel?: (HelixHeadlessLog["doneLabel"]) | undefined;
+  /** What the line above the log says once `limit` has let lines go. `{count}` is how many. */
+  "dropped-label"?: (HelixHeadlessLog["droppedLabel"]) | undefined;
+  /** What the line above the log says once `limit` has let lines go. `{count}` is how many. */
+  droppedLabel?: (HelixHeadlessLog["droppedLabel"]) | undefined;
+  /** The text shown and announced when the log has no lines. */
+  "empty-text"?: (HelixHeadlessLog["emptyText"]) | undefined;
+  /** The text shown and announced when the log has no lines. */
+  emptyText?: (HelixHeadlessLog["emptyText"]) | undefined;
+  /** What a screen reader hears when lines at `error` arrive. `{count}` is how
+many arrived together and `{text}` is the first of them. */
+  "error-label"?: (HelixHeadlessLog["errorLabel"]) | undefined;
+  /** What a screen reader hears when lines at `error` arrive. `{count}` is how
+many arrived together and `{text}` is the first of them. */
+  errorLabel?: (HelixHeadlessLog["errorLabel"]) | undefined;
+  /** The log's name, read by screen readers, where `label` is empty. */
+  "fallback-label"?: (HelixHeadlessLog["fallbackLabel"]) | undefined;
+  /** The log's name, read by screen readers, where `label` is empty. */
+  fallbackLabel?: (HelixHeadlessLog["fallbackLabel"]) | undefined;
+  /** What a screen reader hears when a step finishes or fails. `{heading}` is
+the step's heading and `{status}` is `done` or `failed`. */
+  "group-label"?: (HelixHeadlessLog["groupLabel"]) | undefined;
+  /** What a screen reader hears when a step finishes or fails. `{heading}` is
+the step's heading and `{status}` is `done` or `failed`. */
+  groupLabel?: (HelixHeadlessLog["groupLabel"]) | undefined;
+  /** The log's name, read by screen readers. */
+  label?: (HelixHeadlessLog["label"]) | undefined;
+  /** The most lines kept, or 0 to keep them all. Past it the oldest lines are
+let go, and the line above the log says how many. */
+  limit?: (HelixHeadlessLog["limit"]) | undefined;
+  /** A link for each line number, with `{n}` where the number goes, such as
+`#L{n}`. Empty leaves the numbers as text. */
+  "line-href"?: (HelixHeadlessLog["lineHref"]) | undefined;
+  /** A link for each line number, with `{n}` where the number goes, such as
+`#L{n}`. Empty leaves the numbers as text. */
+  lineHref?: (HelixHeadlessLog["lineHref"]) | undefined;
+  /** What a screen reader hears for the link on a line's number, handed to each
+line the log draws. `{number}` is the number. */
+  "line-label"?: (HelixHeadlessLog["lineLabel"]) | undefined;
+  /** What a screen reader hears for the link on a line's number, handed to each
+line the log draws. `{number}` is the number. */
+  lineLabel?: (HelixHeadlessLog["lineLabel"]) | undefined;
+  /** Whether each line shows its number. */
+  "line-numbers"?: (HelixHeadlessLog["lineNumbers"]) | undefined;
+  /** Whether each line shows its number. */
+  lineNumbers?: (HelixHeadlessLog["lineNumbers"]) | undefined;
+  /** Lines to mark, as numbers and ranges such as `12, 40-44`. */
+  "mark-lines"?: (HelixHeadlessLog["markLines"]) | undefined;
+  /** Lines to mark, as numbers and ranges such as `12, 40-44`. */
+  markLines?: (HelixHeadlessLog["markLines"]) | undefined;
+  /** What a screen reader hears when `query` changes. `{count}` is how many lines match. */
+  "matches-label"?: (HelixHeadlessLog["matchesLabel"]) | undefined;
+  /** What a screen reader hears when `query` changes. `{count}` is how many lines match. */
+  matchesLabel?: (HelixHeadlessLog["matchesLabel"]) | undefined;
+  /** Whether the log follows its newest line.
+
+The reader's scrolling asks first: `helix-before-pin` is cancelable, so a
+consumer refusing it takes the decision and assigns their own value. Not
+reflected, for the reason `Chat` gives at its own `pinned`: a default of
+true would write the attribute on upgrade. */
+  pinned?: (HelixHeadlessLog["pinned"]) | undefined;
+  /** Text a line has to hold to be shown, ignoring case. Empty shows every line. */
+  query?: (HelixHeadlessLog["query"]) | undefined;
+  /** The words on the button that returns to the newest line, where `resume` is empty. */
+  "resume-label"?: (HelixHeadlessLog["resumeLabel"]) | undefined;
+  /** The words on the button that returns to the newest line, where `resume` is empty. */
+  resumeLabel?: (HelixHeadlessLog["resumeLabel"]) | undefined;
+  /** How near the newest line still counts as being at it, in pixels. */
+  threshold?: (HelixHeadlessLog["threshold"]) | undefined;
+  /** How each line shows its `at`: `absolute` on the clock, `relative` as the
+time since the first line. Absent shows no time. */
+  timestamps?: (HelixHeadlessLog["timestamps"]) | undefined;
+  /** Whether a line longer than the box wraps onto the next row. Otherwise the log scrolls sideways. */
+  wrap?: (HelixHeadlessLog["wrap"]) | undefined;
+  /** Whether the rows are still loading.
+
+Reflected, because a stylesheet needs it: the rows that are already there
+are dimmed rather than removed while a new set arrives, and only CSS can
+say that without the component knowing what a row looks like. */
+  loading?: (HelixHeadlessLog["loading"]) | undefined;
+  /** The text shown and announced while the rows load. */
+  "loading-text"?: (HelixHeadlessLog["loadingText"]) | undefined;
+  /** The text shown and announced while the rows load. */
+  loadingText?: (HelixHeadlessLog["loadingText"]) | undefined;
+  /** The steps the lines from data name in `group`. A step stands where its
+first line is, and one with no line yet stands at the end.
+
+Replaced rather than mutated, as `lines` is: a step finishing is a new
+array with its `status` changed. */
+  groups?: (HelixHeadlessLog["groups"]) | undefined;
+  /** The lines as data. Reading it gives every line kept, oldest first, with
+the line still being written left out.
+
+Replaced rather than mutated: setting it starts the log over with these
+lines, and `write` adds to them. Set it or write children, not both. */
+  lines?: (HelixHeadlessLog["lines"]) | undefined;
+  /** Reads each finished line of written text: return the fields to set, such
+as `level` or `group`, or `null` to drop the line. Lines in `lines` are
+taken as they are. */
+  parse?: (HelixHeadlessLog["parse"]) | undefined;
+  /** Text to read as it arrives, to the end: a `ReadableStream` of text or
+bytes, such as a `fetch` response's body, or an async iterable. Bytes are
+read as UTF-8. The log sets `done` when it ends, and a new source stops
+reading the last one. */
+  source?: (HelixHeadlessLog["source"]) | undefined;
+};
+
+export type HelixHeadlessLogVueEvents = {
+  /** Fired when the reader leaves the newest line by scrolling, or comes back to it. Cancelable. */
+  "helix-before-pin": HelixHeadlessLogHelixBeforePinElementEvent;
+  /** Fired after a reader opens or closes a group drawn from `groups`, with the `id` of every open group in `detail.value`, separated by commas. */
+  "helix-expand": HelixHeadlessLogHelixExpandElementEvent;
+  /** Fired after the log follows the newest line or lets go of it, with `true` or `false` in `detail.value`. */
+  "helix-pin": HelixHeadlessLogHelixPinElementEvent;
+};
+
 /** `HelixHeadlessMapArea` component event */
 export type HelixHeadlessMapAreaElementEvent<E = Event> = TypedEvent<
   HelixHeadlessMapArea,
@@ -20229,6 +20448,48 @@ export type CustomCssProperties = {
   "--list-first"?: (string) | undefined;
   /** What each row adds to the number before it: `1`, or `-1` where `reversed`. */
   "--list-step"?: (string) | undefined;
+  /** Written on a `run` with a background, in the same form as `--log-run-color`. */
+  "--log-run-background-color"?: (string) | undefined;
+  /** Written on a `run` with a text color: one of the sixteen `--log-ansi-*` colors the log publishes, or the color itself. */
+  "--log-run-color"?: (string) | undefined;
+  /** The background a run takes where ANSI swaps the colors and named none. Defaults to the log's own background on the styled tier. */
+  "--log-ansi-background"?: (string) | undefined;
+  /** The ANSI color black, which codes `30` and `40` draw. */
+  "--log-ansi-black"?: (string) | undefined;
+  /** The ANSI color blue, which codes `34` and `44` draw. */
+  "--log-ansi-blue"?: (string) | undefined;
+  /** The ANSI color bright black, which codes `90` and `100` draw. */
+  "--log-ansi-bright-black"?: (string) | undefined;
+  /** The ANSI color bright blue, which codes `94` and `104` draw. */
+  "--log-ansi-bright-blue"?: (string) | undefined;
+  /** The ANSI color bright cyan, which codes `96` and `106` draw. */
+  "--log-ansi-bright-cyan"?: (string) | undefined;
+  /** The ANSI color bright green, which codes `92` and `102` draw. */
+  "--log-ansi-bright-green"?: (string) | undefined;
+  /** The ANSI color bright magenta, which codes `95` and `105` draw. */
+  "--log-ansi-bright-magenta"?: (string) | undefined;
+  /** The ANSI color bright red, which codes `91` and `101` draw. */
+  "--log-ansi-bright-red"?: (string) | undefined;
+  /** The ANSI color bright white, which codes `97` and `107` draw. */
+  "--log-ansi-bright-white"?: (string) | undefined;
+  /** The ANSI color bright yellow, which codes `93` and `103` draw. */
+  "--log-ansi-bright-yellow"?: (string) | undefined;
+  /** The ANSI color cyan, which codes `36` and `46` draw. */
+  "--log-ansi-cyan"?: (string) | undefined;
+  /** The text color a run takes where ANSI swaps the colors and named none. Defaults to the log's own text color on the styled tier. */
+  "--log-ansi-foreground"?: (string) | undefined;
+  /** The ANSI color green, which codes `32` and `42` draw. */
+  "--log-ansi-green"?: (string) | undefined;
+  /** The ANSI color magenta, which codes `35` and `45` draw. */
+  "--log-ansi-magenta"?: (string) | undefined;
+  /** The ANSI color red, which codes `31` and `41` draw. */
+  "--log-ansi-red"?: (string) | undefined;
+  /** The ANSI color white, which codes `37` and `47` draw. */
+  "--log-ansi-white"?: (string) | undefined;
+  /** The ANSI color yellow, which codes `33` and `43` draw. */
+  "--log-ansi-yellow"?: (string) | undefined;
+  /** Written on the `log`: how many digits the largest line number has, while `line-numbers` is set, so a stylesheet can size the column of numbers. */
+  "--log-digits"?: (string) | undefined;
   /** How far the needle turns to point north, as an angle. The frame writes it from `bearing`. */
   "--map-needle-turn"?: (string) | undefined;
   /** The height of the panel this one took over from, written on the surface while it is open. */
@@ -20739,6 +21000,24 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLoaderVueProps,
     HelixHeadlessLoaderVueEvents
   >;
+  /** A group is a disclosure: its heading is a button that shows and hides the lines inside it, and says whether they are shown with 'aria-expanded'. Put 'Log.Line' elements inside it, and nest groups for steps within steps.  'status' draws a mark before the heading, and a screen reader hears the status after the heading ('status-label'). 'duration' stands at the end of the heading, as you write it, such as '12s'.  A group starts shut. Write 'default-open' on the step a reader should see, such as the one that failed. */
+  "helix-headless-log-group": DefineCustomElement<
+    HelixHeadlessLogGroup,
+    HelixHeadlessLogGroupVueProps,
+    HelixHeadlessLogGroupVueEvents
+  >;
+  /** Write one for each line of a log you serve whole, inside a 'Log' or a 'Log.Group'. The log numbers each line, counting the lines of every group, and tells it whether to show its number and its time.  'level' says how much a line matters, and the styled tier draws 'warn' and 'error' lines apart. The text is the line's own content, so you can mark it up yourself. */
+  "helix-headless-log-line": DefineCustomElement<
+    HelixHeadlessLogLine,
+    HelixHeadlessLogLineVueProps,
+    HelixHeadlessLogLineVueEvents
+  >;
+  /** A log holds lines in the order they were written and keeps the reader at the newest one, until they scroll up to read. It stays where they left it while lines keep arriving, and a button returns them to the end ('resume-label', "Jump to latest").  **Lines arrive two ways.** For a log you serve whole, write 'Log.Line' elements as children, inside 'Log.Group' elements for the steps. For a log that is still being written, hand it text: 'write(chunk)' takes text as it arrives, in pieces that need not end at a line break, and 'source' takes a 'ReadableStream' or an async iterable and reads it to the end. 'lines' takes the lines as data. Text drawn from data is drawn one window at a time, so a log of a hundred thousand lines holds a screenful of elements, and the log needs a block size of its own. Do not use both ways at once.  **Written text is read the way a terminal shows it.** A carriage return starts the line over, so a progress bar stays one line, and the line still being written is shown as it stands. ANSI colors and weights are drawn, in the sixteen colors the styled tier takes from your theme, and every other escape code is dropped. Give 'parse' a function to read each finished line, such as a level off its prefix or a group off a marker.  **Steps fold.** Lines that name a group in 'groups' stand under its heading, which shows its status and how long it took and opens and closes the lines. A group a reader opens or closes fires 'helix-expand' with every open group.  **Search with 'query'.** The log shows only the lines that hold it, marks each match, opens the groups that hold one, and says how many lines match.  'line-numbers' numbers the lines from the first ever written, so a number still names its line once 'limit' has let older lines go, and 'line-href' makes each number a link, such as '#L{n}'. 'scrollToLine(n)' takes a reader to one. 'timestamps' shows each line's 'at', on the clock or as the time into the run. 'mark-lines' marks lines, such as '12, 40-44'.  **What a screen reader hears.** The log is a 'log' and stays quiet as lines arrive, since reading a build aloud line by line helps nobody. A separate status region says each line at 'error' once it arrives, each step once it finishes or fails, and the end of the run once 'done' is set or 'source' ends. Set 'done' yourself when output you 'write' is complete.  The log scrolls on this tier. It carries 'data-scroller', so following the newest line and drawing a window work with no stylesheet. Give the log a block size, such as 'helix-headless-log::part(log) { block-size: 20rem }'.  '''js import '@fusion.dev/helix/log' ''' */
+  "helix-headless-log": DefineCustomElement<
+    HelixHeadlessLog,
+    HelixHeadlessLogVueProps,
+    HelixHeadlessLogVueEvents
+  >;
   /** 'connectMap' fills the shape as a layer of the map, under its place names. The frame lists each area by its 'label' and 'description' for screen readers.  Set 'caption' to draw words on the map with the area, such as a letter for a search sector, in a color that reads on the map. It is drawn rather than focusable, so it adds nothing to the tab order, and a screen reader reads the area's 'label' in the frame's list. */
   "helix-headless-map-area": DefineCustomElement<
     HelixHeadlessMapArea,

package/types/words.d.ts

@@ -2115,6 +2115,77 @@ declare module '@fusion.dev/helix-core' {
        */
       label: Message
     }
+    'helix-log': {
+      /**
+       * What a screen reader hears when the run is over.
+       *
+       * English: `Finished`
+       */
+      doneLabel: Message
+      /**
+       * What the line above the log says once `limit` has let lines go. `{count}` is how many.
+       *
+       * English: `{count, plural, one {# earlier line is} other {# earlier lines are}} not kept`
+       */
+      droppedLabel: Message
+      /**
+       * The text shown and announced when the log has no lines.
+       *
+       * English: `No output yet`
+       */
+      emptyText: Message
+      /**
+       * What a screen reader hears when lines at `error` arrive. `{count}` is how
+       * many arrived together and `{text}` is the first of them.
+       *
+       * English: `{count, plural, one {Error} other {# errors}}: {text}`
+       */
+      errorLabel: Message
+      /**
+       * The log's name, read by screen readers, where `label` is empty.
+       *
+       * English: `Log`
+       */
+      fallbackLabel: Message
+      /**
+       * What a screen reader hears when a step finishes or fails. `{heading}` is
+       * the step's heading and `{status}` is `done` or `failed`.
+       *
+       * English: `{status, select, failed {{heading} failed} other {{heading} finished}}`
+       */
+      groupLabel: Message
+      /**
+       * What a screen reader hears for the link on a line's number. `{number}` is the number.
+       *
+       * English: `Line {number}`
+       */
+      lineLabel: Message
+      /**
+       * The text shown and announced while the rows load.
+       *
+       * English: `Loading`
+       */
+      loadingText: Message
+      /**
+       * What a screen reader hears when `query` changes. `{count}` is how many lines match.
+       *
+       * English: `{count, plural, =0 {No lines match} one {# line matches} other {# lines match}}`
+       */
+      matchesLabel: Message
+      /**
+       * The words on the button that returns to the newest line, where `resume` is empty.
+       *
+       * English: `Jump to latest`
+       */
+      resumeLabel: Message
+      /**
+       * What a screen reader hears for the status, after the heading.
+       * `{status}` is one of `pending`, `running`, `done`, `failed`, and `skipped`.
+       *
+       * English: `{status, select, pending {waiting} running {running} done {finished} failed {failed} skipped {skipped} other {}}`
+       */
+      statusLabel: Message
+    }
     'helix-map': {
       /**
        * The hint shown when the map, waiting to be pressed with