foldkit-mixins-ui 0.17.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -214,6 +214,14 @@ alike. The Message type comes from `h`, and a Submodel's value type (a
214
214
  RadioGroup's or Tabs' `Value`) from where the `toView` goes, so neither needs
215
215
  writing out.
216
216
 
217
+ Every view takes the view's `h` last, as Foldkit's own views do. At runtime it
218
+ is the same builder everywhere; its type is the point: it carries the Message
219
+ the part of the app being drawn can route (the root's, or a Submodel's own), so
220
+ a handler built for another part's Message is a compile error where it is
221
+ written. Pass it down as a parameter and never keep it, as Foldkit asks: a
222
+ builder kept and used in another frame builds handlers that frame cannot
223
+ deliver.
224
+
217
225
  A button drawn as a button needs no `draw` at all. `Button.view` takes the
218
226
  label, a style, and `@foldkit/ui`'s own config:
219
227
 
@@ -475,7 +483,6 @@ the slots with the matching recipe. Hide text with `U.srOnly` from
475
483
  `Label.view` takes the id that derived.
476
484
 
477
485
  ```ts
478
- import { Icon as MediaIcon } from 'foldkit-media'
479
486
  import { parse } from 'foldkit-media/icons'
480
487
  import { Style } from 'foldkit-mixins'
481
488
  import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
@@ -485,17 +492,16 @@ const Mark = Style.forSlots(IconSlots)(Recipes.Icon({ size: 'sm' }))
485
492
 
486
493
  // `h` is the view's builder. `content` is `Html`.
487
494
  AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
488
- Icon.view({ content: h.span([], ['!']), label: 'Warning', style: Mark }, h)
489
- Icon.view({ content: h.span([], ['!']), style: Mark }, h)
490
495
 
491
- // An icon as data from `foldkit-media`, parsed at build time.
496
+ // An icon as data: an import from `virtual:foldkit-icons/…`, or parsed by a script.
492
497
  const check = parse('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>', 'check')
493
- Icon.view({ content: MediaIcon.draw(check, h), label: 'Done', style: Mark }, h)
498
+ Icon.view({ icon: check, label: 'Done', style: Mark }, h)
499
+ Icon.view({ icon: check, style: Mark }, h)
494
500
  ```
495
501
 
496
502
  A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
497
- `foldkit-media`'s `Icon.draw(icon, h)` draws an `IconData` as inline SVG
498
- (`1em` square alone, `aria-hidden`, ids of its own), and `Icon.view` fills its
503
+ `Icon.view` draws the `IconData` as inline SVG with `foldkit-media`'s
504
+ `Icon.draw` (ids of its own; `key` parts two copies of one icon) and fills its
499
505
  glyph with it, so the recipe's size is the drawing's.
500
506
  `Icons.glyph` is the other tool: a mask on an element that already exists.
501
507
 
@@ -507,7 +513,7 @@ glyph with it, so the recipe's size is the drawing's.
507
513
  | `AspectRatio` | `{ content? }`. Slot `frame`. | `ratio`: `square` (default), `video` (16/9), `portrait` (3/4). The corner reads `radius`. |
508
514
  | `Avatar` | `{ name, src?, initials?, status?, statusLabel? }`. The root is one `role="img"` named by the person (and the status, "Ada Lovelace, Online"); initials show until the picture covers them, the picture's alt empty. `status` (`online`, `away`, `busy`, `offline`) is a dot on the lower end corner. `src` may be an `AvatarPicture` (`{ asset, provider, width }` from `foldkit-media`): the picture is drawn with its 1x and 2x candidates at `width` CSS pixels, and a provider with no URL for it leaves the initials. `Avatar.widthOf(size)` is a size's width in CSS pixels, for that `width`. `Avatar.group({ people, max?, label?, moreLabel?, style?, avatarStyle? })` overlaps them, each ringed in the page, and counts the rest as one more avatar. An avatar beside a name and a line is an `Item` with the avatar as its media. | `size`: `xs`, `sm`, `md` (default), `lg`, `xl`; `shape`: `circle` (default), `rounded`, `square`; `color`: `neutral` (default) or `name` (initials in a hue from the name); `ring`: `none`, `page`, `accent`. Slots `root`, `fallback`, `image`, `status`. `Recipes.AvatarGroup({ overlap: 'tight' \| 'loose' \| 'none' })` over `AvatarGroupSlots` (`root`). |
509
515
  | `Figure` | `{ content, caption? }`: a `figure` holding its content (an `Image.view`, a chart, a code block), then its caption in a `figcaption`, which names the figure for assistive technology by itself; no caption, no `figcaption`. | `align`: `start` (default) or `center`. The caption is the `caption` role, muted. Slots `root`, `caption`. |
510
- | `Image` | `{ asset, provider, layout, alt, priority?, sizes? }` from `foldkit-media`: a `picture` with a `source` per format the provider offers and an `img` with its candidates, `sizes`, `width` and `height` (the box is held before the file arrives), lazy unless `priority` (then `fetchpriority="high"`). `alt` is `Image.described(text)` or `Image.decorative` (`alt=""`, `role="presentation"`), never omitted. The `img` carries `--fk-image-ratio`, `--fk-image-placeholder` (none behind a transparent image) and `data-layout` (`fixed`, `constrained`, `full`); a provider with no URL for the image leaves an empty frame marked `data-unavailable`. An unavailable image keeps its box and is `role="img"` named by its alt text (hidden when decorative). `--fk-image-focus` places a crop at the asset's focal point. `placeholder: 'detail' | 'average'` chooses how much of a ThumbHash to paint; by default the picture for `priority`, the color otherwise. `Image.watchLoad`, beside the style, marks the `img`'s `data-state` (`loading`, `loaded`, `failed`); the recipe hides a failed image, keeping its box. `Image.audit`, beside the style in a development build, warns in the console of an image drawn wider than its file (blurry) or far narrower (wasted bytes), and of more than one image drawn with `priority`. `Image.preloadsIn` is a `foldkit-ssr` `Head`: the `<link rel="preload">` of each image the rendered page drew with `priority`. | `fit`: `cover` (default) or `contain`; `edge`: `none` (default) or `line` (the faint inset line); `ratio`: `auto` (default), `square`, `video` (16:9), `portrait` (3:4), cropped at the asset's focal point (an unavailable image holds the cropped box); `radius`: `none` (default), `sm`, `md`, `lg`, `full`. The placeholder paints the `img`'s background. Slots `frame`, `source`, `image`. |
516
+ | `Image` | `{ asset, provider, layout, alt, priority?, sizes? }` from `foldkit-media`: a `picture` with a `source` per format the provider offers and an `img` with its candidates, `sizes`, `width` and `height` (the box is held before the file arrives), lazy unless `priority` (then `fetchpriority="high"`). `alt` is what the image shows in words (a string, or `Image.described(text)`) or `Image.decorative` (`alt=""`, `role="presentation"`), never omitted. `Provider.hosted` takes only a `HashedAsset`, so facts without a content hash are a type error there. The `img` carries `--fk-image-ratio`, `--fk-image-placeholder` (none behind a transparent image) and `data-layout` (`fixed`, `constrained`, `full`); a provider with no URL for the image leaves an empty frame marked `data-unavailable`. An unavailable image keeps its box and is `role="img"` named by its alt text (hidden when decorative). `--fk-image-focus` places a crop at the asset's focal point. `placeholder: 'detail' | 'average'` chooses how much of a ThumbHash to paint; by default the picture for `priority`, the color otherwise. `Image.watchLoad`, beside the style, marks the `img`'s `data-state` (`loading`, `loaded`, `failed`); the recipe hides a failed image, keeping its box. `Image.audit`, beside the style in a development build, warns in the console of an image drawn wider than its file (blurry) or far narrower (wasted bytes), and of more than one image drawn with `priority`. `Image.preloadsIn` is a `foldkit-ssr` `Head`: the `<link rel="preload">` of each image the rendered page drew with `priority`. | `fit`: `cover` (default) or `contain`; `edge`: `none` (default) or `line` (the faint inset line); `ratio`: `auto` (default), `square`, `video` (16:9), `portrait` (3:4), cropped at the asset's focal point (an unavailable image holds the cropped box); `radius`: `none` (default), `sm`, `md`, `lg`, `full`. The placeholder paints the `img`'s background. Slots `frame`, `source`, `image`. |
511
517
  | `Badge` | `{ text, tone? }` writes `data-tone`. | `Recipes.Badge({ attribute, tones, appearance? })` maps that attribute; values outside the map keep the base. `appearance`: `tinted` (default), `dot`, `outline`, `solid`. Slot `badge`. |
512
518
  | `Breadcrumb` | `{ steps: { label, href?, current?, icon? }[], separator?, collapse? }`. `current` is text with `aria-current="page"`; the others are links. An `icon` draws before its label, hidden from assistive technology. `separator` is drawn between steps in place of the recipe's; `collapse: { max, onExpand, label? }` folds the middle of a long trail into an ellipsis (`Breadcrumb.collapsedOf(steps, max)` is the split). `collapse: { max, menu: { model, onMessage, mixins } }` makes the ellipsis open a Menu of the hidden steps instead: the Menu's Model is the application's, built from `Breadcrumb.menuRows(steps, max)`, and `Breadcrumb.chosen(steps, max, value)` is the step a row leads to. | `separator`: `slash` (default), `chevron` or `dot`, drawn where the view is given no `separator` of its own. Slots `root`, `list`, `item`, `link`, `current`, `icon`, `separator`, `ellipsis`, `dots`. |
513
519
  | `ButtonGroup` | `{ label, items, orientation?, separated? }`. `role="group"`, joining its items: borders overlap by one and only the outer corners stay round. An item is the caller's button, field or Menu (a wrapper passes the corners to the face it holds), or a string, drawn in the `text` box (a count, a field's prefix). `orientation: 'vertical'` stacks them; `separated` draws a rule on every seam, for solid buttons whose fills meet. A hovered or focused item rises over its neighbour. `Segmented` is the control that selects. | `size`: `sm`, `md`, `lg`, for every item with no size of its own; `width: 'fill'` spans the container, a field taking what the buttons leave. Slots `root`, `separator`, `text`. |
@@ -639,17 +645,21 @@ What a recipe assumes and does:
639
645
  pointer, so iOS Safari does not zoom the page into it.
640
646
  - **A state is a tint, not a surface.** An unfilled control's hover is a
641
647
  faint film of the state ink over whatever is under it, so it reads on a
642
- muted page, a colored band or an inverted panel. The ink is the theme's
648
+ muted page, a colored band or an inverted panel; a press lays that film
649
+ stronger (`state.press`, 1.75 of the hover's). The ink is the theme's
643
650
  `--fk-state-ink` (`state.ink`: the element's own text, or the accent's ink
644
- under `stateHue: 'accent'`) unless a painted surface above names its paint
651
+ under `surface.hover: 'accent'`) unless a painted surface above names its paint
645
652
  in the local `--_fk-state-ink`: the accent and danger tones name their
646
653
  fill, a subtle alert band its ink and a bold one its fill, so a hover on
647
654
  blue is a deeper blue. The neutral and ink tones name the theme's ink back,
648
655
  so a neutral control on a band does not take the band's hue, and one
649
- `stateHue` override reaches every component. The neutral button is
656
+ `surface.hover` choice reaches every component. The neutral button is
650
657
  see-through (`state.tint`), and images carry a hairline inside their edge
651
658
  (`state.edge`). A popup's rows round concentrically inside its panel
652
- (`Theme.nested`), as a segmented option does inside its tray.
659
+ (`Theme.nested`), as a segmented option does inside its tray. A fluid
660
+ highlight — Table's, Segmented's, pill Tabs', Nav's, TreeView's, a Card
661
+ group's — lays that same film, so `surface.hover` and
662
+ `surface.hoverStrength` move it with every other hover.
653
663
  - **Popups and dialogs enter and leave** when drawn with `@foldkit/ui`'s
654
664
  `isAnimated` (the Menu component's `Menu.init(id, rows, { isAnimated:
655
665
  true })`): a popup fades and grows on the fast tier, from the side its
@@ -663,8 +673,12 @@ What a recipe assumes and does:
663
673
  pressed toggle (`aria-pressed="true"`) rests on its tone's fill, a solid
664
674
  one on the `active` fill; hovered, a solid toggle keeps it and an unfilled
665
675
  one takes its tone's hover fill; held, it deepens to the `active` fill; and
666
- its text stays the fill's throughout. Chosen rows next to each other in a multiple listbox or
667
- combobox merge into one block.
676
+ its text stays the fill's throughout. A hovered row, tab, menu item or
677
+ accordion row darkens while the press is held, and a fluid highlight darkens
678
+ with the item it lights (`FluidHover` marks the container `data-fluid-held`).
679
+ Chosen rows next to each other in a multiple listbox or
680
+ combobox merge into one block. A disabled control fades by
681
+ `state.disabledOpacity` (half by default), so one page shows one fade.
668
682
  - **Raised surfaces nest.** Popups, popovers, date picker panels and toasts
669
683
  sit two levels above what holds them and dialogs four (`Theme.raise`), each
670
684
  painted for its level, so a popover in a dialog lands above the dialog: a
@@ -834,8 +848,10 @@ sets no `display`: the Builder owns its narrow tabs' visibility) or an `underlin
834
848
  the tray and its options on the ladder (`xs` a half step below compact, 24px), the
835
849
  tray's inset counted in, so a tray is as tall as a button beside it. Its `indicator` and `highlight` slots, drawn first in the group
836
850
  and given `Segmented.fluid`, slide the pressed option's pill to a new press
837
- and move a faint pill to the option the pointer is on; until it runs the
838
- pressed option fills itself:
851
+ and move the hover to the option the pointer is on, tinted as every hover is
852
+ (the theme's `surface.hover` and `surface.hoverStrength`; a plain tray's
853
+ options tint themselves the same); until it runs the pressed option fills
854
+ itself:
839
855
 
840
856
  ```ts
841
857
  const SegmentedStyle = Style.forSlots(SegmentedSlots)(
package/dist/index.d.mts CHANGED
@@ -264,9 +264,9 @@ type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
264
264
  * provider of its variants, and how wide the avatar is drawn in CSS pixels,
265
265
  * so a 24px avatar fetches a 48px variant, not the original.
266
266
  */
267
- interface AvatarPicture {
268
- readonly asset: ImageAsset;
269
- readonly provider: Provider.Provider;
267
+ interface AvatarPicture<Asset extends ImageAsset = ImageAsset> {
268
+ readonly asset: Asset;
269
+ readonly provider: Provider.Provider<NoInfer<Asset>>;
270
270
  readonly width: number;
271
271
  }
272
272
  /**
@@ -274,14 +274,14 @@ interface AvatarPicture {
274
274
  * style for its slots, and mixins beside the style. No upstream component
275
275
  * stands behind it.
276
276
  */
277
- interface AvatarView<Message = never> {
277
+ interface AvatarView<Message = never, Asset extends ImageAsset = ImageAsset> {
278
278
  /** Who the avatar shows: its accessible name, its initials and its hue. */
279
279
  readonly name: string;
280
280
  /**
281
281
  * The picture: a URL, or an `AvatarPicture` drawn with its candidates.
282
282
  * Without one, or with a provider that has no URL for it, the initials stand alone.
283
283
  */
284
- readonly src?: string | AvatarPicture | undefined;
284
+ readonly src?: string | AvatarPicture<Asset> | undefined;
285
285
  /** What the disc says in place of initials taken from the name (a group's `+3`). */
286
286
  readonly initials?: string | undefined;
287
287
  readonly status?: AvatarStatus | undefined;
@@ -292,7 +292,7 @@ interface AvatarView<Message = never> {
292
292
  /** Mixins beside the style. */
293
293
  readonly mixins?: MixinList<Message> | undefined;
294
294
  }
295
- declare const view$67: <Message = never>(options: AvatarView<Message>, h: HtmlBuilder<Message>) => Html;
295
+ declare const view$67: <Message = never, Asset extends ImageAsset = ImageAsset>(options: AvatarView<Message, Asset>, h: HtmlBuilder<Message>) => Html;
296
296
  /**
297
297
  * A group publishes its frame; each avatar in it is an `AvatarSlots`
298
298
  * avatar, and the count of those left out is one more, so it takes the same
@@ -303,8 +303,8 @@ export declare const AvatarGroupSlots: Slots.Contract<{
303
303
  readonly root: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
304
304
  }>;
305
305
  /** Avatars overlapping in a row, at most `max` of them and a `+N` for the rest. */
306
- interface AvatarGroupView<Message = never> {
307
- readonly people: ReadonlyArray<Omit<AvatarView<Message>, 'style' | 'mixins'>>;
306
+ interface AvatarGroupView<Message = never, Asset extends ImageAsset = ImageAsset> {
307
+ readonly people: ReadonlyArray<Omit<AvatarView<Message, Asset>, 'style' | 'mixins'>>;
308
308
  /** How many to draw before the `+N`; every one when omitted. */
309
309
  readonly max?: number | undefined;
310
310
  /** The group's accessible name, such as "Editors". */
@@ -318,7 +318,7 @@ interface AvatarGroupView<Message = never> {
318
318
  /** Mixins beside the style. */
319
319
  readonly mixins?: MixinList<Message> | undefined;
320
320
  }
321
- declare const group$3: <Message = never>(options: AvatarGroupView<Message>, h: HtmlBuilder<Message>) => Html;
321
+ declare const group$3: <Message = never, Asset extends ImageAsset = ImageAsset>(options: AvatarGroupView<Message, Asset>, h: HtmlBuilder<Message>) => Html;
322
322
  declare namespace figure_d_exports {
323
323
  export { FigureSlots, FigureView, view$66 as view };
324
324
  }
@@ -372,12 +372,16 @@ type Alt = typeof Alt.Type;
372
372
  declare const described: (text: string) => Alt;
373
373
  declare const decorative: Alt;
374
374
  /** An image in one call: its facts, where its variants live, how wide it is drawn, and what it says. */
375
- interface ImageView<Message = never> {
376
- readonly asset: ImageAsset;
377
- readonly provider: Provider.Provider;
375
+ interface ImageView<Message = never, Asset extends ImageAsset = ImageAsset> {
376
+ readonly asset: Asset;
377
+ /** Where its variants live: `Provider.hosted` takes only facts with a content hash. */
378
+ readonly provider: Provider.Provider<NoInfer<Asset>>;
378
379
  readonly layout: Layout.Layout;
379
- /** Required: an image either says something or is ornament, and the page must say which. */
380
- readonly alt: Alt;
380
+ /**
381
+ * Required: an image either says something or is ornament, and the page
382
+ * must say which: what it shows in words (as `described(text)`), or `decorative`.
383
+ */
384
+ readonly alt: string | Alt;
381
385
  /** The page's largest image: fetched first, not lazily. */
382
386
  readonly priority?: boolean | undefined;
383
387
  /** In place of the layout's `sizes`, when the page knows the drawn width better. */
@@ -392,7 +396,7 @@ interface ImageView<Message = never> {
392
396
  /** Mixins beside the style. */
393
397
  readonly mixins?: MixinList<Message> | undefined;
394
398
  }
395
- declare const view$65: <Message = never>(options: ImageView<Message>, h: HtmlBuilder<Message>) => Html;
399
+ declare const view$65: <Message = never, Asset extends ImageAsset = ImageAsset>(options: ImageView<Message, Asset>, h: HtmlBuilder<Message>) => Html;
396
400
  /**
397
401
  * Marks the `img`'s `data-state` (`loading`, `loaded`, `failed`), for a style
398
402
  * to read; `Recipes.Image` hides a failed image, keeping its box, so no
@@ -5083,6 +5087,8 @@ declare const view$34: import("foldkit/submodel").View<{
5083
5087
  };
5084
5088
  }, {
5085
5089
  readonly _tag: "Closed";
5090
+ } | {
5091
+ readonly _tag: "Opened";
5086
5092
  } | {
5087
5093
  readonly _tag: "Cleared";
5088
5094
  } | {
@@ -5143,6 +5149,10 @@ declare const view$34: import("foldkit/submodel").View<{
5143
5149
  readonly _tag: "IgnoredMouseClick";
5144
5150
  } | {
5145
5151
  readonly _tag: "SuppressedSpaceScroll";
5152
+ } | {
5153
+ readonly _tag: "RequestedClose";
5154
+ } | {
5155
+ readonly _tag: "RequestedOpen";
5146
5156
  } | {
5147
5157
  readonly _tag: "BlurredPanel";
5148
5158
  } | {
@@ -5168,13 +5178,7 @@ declare const view$34: import("foldkit/submodel").View<{
5168
5178
  readonly _tag: "PressedPointerOnButton";
5169
5179
  readonly pointerType: string;
5170
5180
  readonly button: number;
5171
- } | {
5172
- readonly _tag: "RequestedClose";
5173
- } | {
5174
- readonly _tag: "RequestedOpen";
5175
5181
  };
5176
- } | {
5177
- readonly _tag: "Opened";
5178
5182
  } | {
5179
5183
  readonly _tag: "RequestedSelectDate";
5180
5184
  readonly date: {
@@ -5461,11 +5465,14 @@ export declare const IconSlots: Slots.Contract<{
5461
5465
  readonly glyph: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>;
5462
5466
  }>;
5463
5467
  /**
5464
- * An icon in one call: the drawing it holds, the name it has when it means
5468
+ * An icon in one call: the icon it draws, the name it has when it means
5465
5469
  * something, a style for its slot, and mixins beside the style.
5466
5470
  */
5467
5471
  interface IconView<Message = never> {
5468
- readonly content: Html;
5472
+ /** An icon as data: an import from `virtual:foldkit-icons/…`, or a package's constant. */
5473
+ readonly icon: IconData;
5474
+ /** Parts two copies of one icon on a page, whose ids would otherwise collide (`Icon.draw`'s `key`). */
5475
+ readonly key?: string | undefined;
5469
5476
  /** Announced as an image. Omitted, the icon is decorative. */
5470
5477
  readonly label?: string | undefined;
5471
5478
  /** A style of `IconSlots`, for the glyph's look. */
@@ -7909,7 +7916,6 @@ declare const Segmented: import("foldkit-mixins").SlotRecipe<import("foldkit-mix
7909
7916
  underline: {
7910
7917
  group: import("foldkit-mixins").StyleValue;
7911
7918
  indicator: import("foldkit-mixins").StyleValue;
7912
- highlight: import("foldkit-mixins").StyleValue;
7913
7919
  };
7914
7920
  };
7915
7921
  size: {