@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/docs/avatar.md

@@ -0,0 +1,238 @@
+# Avatar and AvatarGroup
+
+> Display · @motifx-community/ui 0.1.0-beta.0
+
+Someone’s picture, or their initials, or a person icon, with their presence on its corner. A group stacks or spreads them and counts the ones it does not show.
+
+## Import
+
+```tsx
+import { Avatar, AvatarGroup } from '@motifx-community/ui';
+```
+
+## From JSX and from code
+
+Every prop takes a value or a function. Created with `new`, the same properties are set from code.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Avatar, Button, Stack, type AvatarStatus } from '@motifx-community/ui';
+
+const PEOPLE = ['Ada Lovelace', 'Alan Turing', 'Grace Hopper'];
+const STATUSES: AvatarStatus[] = ['online', 'away', 'busy', 'offline'];
+
+/** An avatar from JSX follows its functions; one made with `new` takes the same properties from code. */
+export default function FromCode() {
+  const s = reactive({ person: 0, status: 0 });
+  const coded = new Avatar({ name: 'Edsger Dijkstra', tone: 'success', shape: 'square' });
+
+  return (
+    <Stack orientation="horizontal" wrap align="center">
+      <Avatar name={() => PEOPLE[s.person]} status={() => STATUSES[s.status]} />
+      <Button text="Next person" variant="outline" onclick={() => (s.person = (s.person + 1) % PEOPLE.length)} />
+      <Button text="Next presence" variant="outline" onclick={() => (s.status = (s.status + 1) % STATUSES.length)} />
+      <span onConfig={(c) => c.controls.add(coded)} />
+    </Stack>
+  );
+}
+```
+
+## Picture, initials, icon
+
+The picture shows once it has loaded; until then, and when it cannot load, the initials show. Without a name the person icon does.
+
+```tsx
+import { Avatar, Stack } from '@motifx-community/ui';
+
+// A picture of our own, so the example needs no network: a sunset as an SVG.
+const PICTURE = `data:image/svg+xml,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><defs><linearGradient id="sky" x2="0" y2="1">' +
+    '<stop offset="0" stop-color="#3b5bdb"/><stop offset="1" stop-color="#f08c00"/></linearGradient></defs>' +
+    '<rect width="64" height="64" fill="url(#sky)"/><circle cx="32" cy="40" r="12" fill="#ffd43b"/>' +
+    '<path d="M0 46h64v18H0z" fill="#2b8a3e"/></svg>',
+)}`;
+
+/** A picture; initials when there is none or it cannot load; a person icon without a name. */
+export default function Content() {
+  return (
+    <Stack orientation="horizontal" wrap align="center">
+      <Avatar name="Ada Lovelace" src={PICTURE} />
+      <Avatar name="Ada Lovelace" />
+      <Avatar name="Alan Turing" src="does-not-exist.png" />
+      <Avatar initials="QA" label="Quality team" />
+      <Avatar />
+    </Stack>
+  );
+}
+```
+
+## Tones and shapes
+
+```tsx
+import { Avatar, Stack, type AvatarShape, type AvatarTone } from '@motifx-community/ui';
+
+const TONES: AvatarTone[] = ['standard', 'accent', 'info', 'success', 'caution', 'danger'];
+const SHAPES: AvatarShape[] = ['circle', 'square'];
+const PEOPLE = ['Ada Lovelace', 'Alan Turing', 'Grace Hopper', 'Edsger Dijkstra', 'Barbara Liskov', 'Linus Torvalds'];
+
+/** Every tone in each shape; `auto` takes a tone from the name, the same for the same name. */
+export default function Tones() {
+  return (
+    <Stack>
+      {SHAPES.map((shape) => (
+        <Stack key={shape} orientation="horizontal" wrap align="center">
+          {TONES.map((tone) => (
+            <Avatar key={tone} name={tone} tone={tone} shape={shape} label={`${tone}, ${shape}`} />
+          ))}
+        </Stack>
+      ))}
+      <Stack orientation="horizontal" wrap align="center">
+        {PEOPLE.map((name) => (
+          <Avatar key={name} name={name} tone="auto" />
+        ))}
+      </Stack>
+    </Stack>
+  );
+}
+```
+
+## Sizes and presence
+
+```tsx
+import { Avatar, Stack, type AvatarSize, type AvatarStatus } from '@motifx-community/ui';
+
+const SIZES: AvatarSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];
+const STATUSES: AvatarStatus[] = ['online', 'away', 'busy', 'offline'];
+
+/** Each size, with each presence. */
+export default function Sizes() {
+  return (
+    <Stack>
+      {STATUSES.map((status) => (
+        <Stack key={status} orientation="horizontal" wrap align="center">
+          {SIZES.map((size) => (
+            <Avatar key={size} name="Grace Hopper" size={size} status={status} />
+          ))}
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
+```
+
+## Groups
+
+`max` shows that many and counts the rest in a `+N`; `total` counts those not given as well. The group sets the size of all its avatars.
+
+```tsx
+import { Avatar, AvatarGroup, Stack } from '@motifx-community/ui';
+
+const TEAM = ['Ada Lovelace', 'Alan Turing', 'Grace Hopper', 'Edsger Dijkstra', 'Barbara Liskov'];
+
+/** Stacked with the rest counted, side by side, and a total larger than the avatars given. */
+export default function Groups() {
+  return (
+    <Stack gap="lg">
+      <AvatarGroup max={3} label="Team">
+        {TEAM.map((name) => (
+          <Avatar key={name} name={name} />
+        ))}
+      </AvatarGroup>
+      <AvatarGroup layout="spread" size="sm" label="Team">
+        {TEAM.map((name) => (
+          <Avatar key={name} name={name} />
+        ))}
+      </AvatarGroup>
+      <AvatarGroup size="lg" total={42} label="Followers">
+        {TEAM.slice(0, 3).map((name) => (
+          <Avatar key={name} name={name} />
+        ))}
+      </AvatarGroup>
+    </Stack>
+  );
+}
+```
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Name` | With a name or a label the avatar is an image with that name (`role="img"`); the presence is said after it (“Ada Lovelace, Away”). |
+| `No name` | An avatar with nothing to say (no name, no label, no presence) is hidden from screen readers. |
+| `Picture` | The picture has an empty `alt`: the avatar itself carries the name. |
+| `Group` | `role="group"` with its label; the `+N` says how many are not shown (“8 more people”). |
+| `Colour` | The presence is not said by colour alone: it is in the name screen readers hear, and Fluent draws a mark in the dot. |
+
+## Localization
+
+Initials are written in the capitals of the kit language (`uiLocale`): “ilgin” is “İ” in Turkish. The presence and the `+N` texts are kit texts (`presenceOnline` … `presenceOffline`, `avatarPresence`, `moreItems`, `avatarGroupMore`) and change with it.
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-avatar` | The avatar. `data-size`, `data-shape`, `data-tone`. |
+| `.mx-avatar__image` | The picture. `data-pending` until it loads. |
+| `.mx-avatar__initials, .mx-avatar__icon` | The initials, and the person icon shown without them. |
+| `.mx-avatar__status` | The presence dot. `data-status`. |
+| `.mx-avatar-group` | The group. `data-size`, `data-layout`; an avatar it does not show has `data-beyond`. |
+| `.mx-avatar-group__more` | The `+N` avatar. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `avatar.avatar` | Unit: the avatar at rest (the standard tone) and in each tone. |
+| `avatar.icon, avatar.status, avatar.status-icon` | Units: the person icon; the presence dot (its ring, per presence); a mark inside the dot, per presence. |
+| `avatar.size.*, avatar.font-size.*, avatar.icon-size.*, avatar.status-size.*, avatar.square-radius.*` | The avatar, its initials, its icon, its dot and its square corners, per size. |
+| `avatar.tone, avatar.shape` | The tone and shape an avatar takes when none is given. |
+| `avatar-group.stacked` | Unit: the ring that parts a stacked avatar from the one it covers. |
+| `avatar-group.overlap.*, avatar-group.gap.*, avatar-group.layout` | How far stacked avatars go under each other, the space between spread ones, and the layout taken when none is given. |
+
+## API reference
+
+### Avatar props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `Bind<string \| null>` | `null` | The picture. Until it loads, or when it cannot, the initials (else the person icon) show. |
+| `name` | `Bind<string>` | `''` | Whose avatar it is: the initials are made from it, and screen readers say it. |
+| `initials` | `Bind<string>` | `''` | Initials of your own instead of the ones made from `name`. |
+| `label` | `Bind<string>` | `''` | What screen readers say instead of the name. |
+| `size` | `Bind<AvatarSize>` | `'md'` | `xs`, `sm`, `md`, `lg`, `xl`. In a group, the group’s. |
+| `shape` | `Bind<AvatarShape>` | the language’s (`circle`) | `circle`, `square` (with the language’s corners for its size). |
+| `tone` | `Bind<AvatarTone>` | the language’s | `standard`, `accent`, `info`, `success`, `caution`, `danger`, or `auto`: one taken from the name, the same for the same name everywhere. Material and Lilac take `accent`, the others `standard`. |
+| `status` | `Bind<AvatarStatus \| null>` | `null` | `online`, `away`, `busy`, `offline`: a presence dot on the lower end corner. |
+| `visible, tabStop` | see Control |  | The shared properties of every control. |
+
+### Avatar properties
+
+| Property | Access | Description |
+| --- | --- | --- |
+| `every prop above` | read/write | A value or a function, like the prop. |
+| `shownInitials` | read-only | The initials it shows: the ones given, else the ones made from the name. |
+| `showsPicture` | read-only | Whether the picture is what shows now (it loaded). |
+
+### AvatarGroup props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `Bind<AvatarSize>` | `'md'` | The size of every avatar in it. |
+| `layout` | `Bind<AvatarGroupLayout>` | the language’s (`stack`) | `stack`: each over the one before it; `spread`: side by side. |
+| `max` | `Bind<number \| null>` | `null` | The most avatars shown; the others are counted in a `+N` after them. |
+| `total` | `Bind<number \| null>` | `null` | How many there are in all, when only some are given; the rest are counted in the `+N`. |
+| `label` | `Bind<string>` | `''` | What screen readers call the group (“Members”). |
+
+### AvatarGroup properties
+
+| Property | Access | Description |
+| --- | --- | --- |
+| `every prop above` | read/write | A value or a function, like the prop. |
+| `avatars` | read-only | The elements of the avatars given, in order, from JSX lists too (the `+N` is not one of them). |
+| `hiddenCount` | read-only | How many are counted in the `+N`; 0 when it does not show. |
+
+### Functions
+
+| Function | Returns | Description |
+| --- | --- | --- |
+| `initialsOf(name, locale)` | `string` | The initials an avatar makes of a name: the first letters of its first and last words, in the capitals of the language. |

package/docs/badge.md

@@ -0,0 +1,193 @@
+# Badge
+
+> Display · @motifx-community/ui 0.1.0-beta.0
+
+A short text, a count or a dot: in a line of text, or on a corner of a button, an avatar or an icon. A count over its maximum shows “99+”, a count of zero hides.
+
+## Import
+
+```tsx
+import { Badge } from '@motifx-community/ui';
+```
+
+## From JSX and from code
+
+Every prop takes a value or a function. Created with `new`, the same properties are set from code.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Badge, Button } from '@motifx-community/ui';
+
+/** A badge from JSX follows its functions; one made with `new` takes the same properties from code. */
+export default function FromCode() {
+  const s = reactive({ unread: 4 });
+  const coded = new Badge({ text: 'Beta', tone: 'info', variant: 'subtle' });
+
+  return (
+    <>
+      <span>
+        Inbox <Badge count={() => s.unread} label={() => `${s.unread} unread`} />
+      </span>
+      <Button text="Add one" variant="outline" onclick={() => s.unread++} />
+      <Button text="Read all" variant="outline" onclick={() => (s.unread = 0)} />
+      <span onConfig={(c) => c.controls.add(coded)}>Search </span>
+    </>
+  );
+}
+```
+
+## Tones and looks
+
+```tsx
+import { Badge, Stack, type BadgeTone, type BadgeVariant } from '@motifx-community/ui';
+
+const TONES: BadgeTone[] = ['standard', 'accent', 'info', 'success', 'caution', 'danger'];
+const VARIANTS: BadgeVariant[] = ['solid', 'subtle', 'outline'];
+
+/** Every tone in each look. */
+export default function Tones() {
+  return (
+    <Stack>
+      {VARIANTS.map((variant) => (
+        <Stack key={variant} orientation="horizontal" wrap align="center">
+          {TONES.map((tone) => (
+            <Badge key={tone} text={tone} tone={tone} variant={variant} />
+          ))}
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
+```
+
+## Counts and dots
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Badge, NumberBox, Stack, Switch } from '@motifx-community/ui';
+
+/** A count up to `max` and `max+` beyond it; at 0 it hides unless `showZero`; a dot says only that there is something. */
+export default function Counts() {
+  const s = reactive({ count: 120, max: 99, showZero: false });
+
+  return (
+    <>
+      <NumberBox label="Count" min={0} x-model={() => s.count} />
+      <NumberBox label="Max" min={1} x-model={() => s.max} />
+      <Switch label="Show zero" x-model={() => s.showZero} />
+      <Stack orientation="horizontal" align="center">
+        <Badge count={() => s.count} max={() => s.max} showZero={() => s.showZero} />
+        <Badge count={() => s.count} max={() => s.max} showZero={() => s.showZero} variant="subtle" />
+        <Badge count={() => s.count} dot label="Something new" />
+      </Stack>
+    </>
+  );
+}
+```
+
+## On a corner
+
+`position` puts the badge on a corner of what it is in. `Badge.attach` does it from code, on any component.
+
+```tsx
+import { Badge, Button, Stack, type BadgePosition } from '@motifx-community/ui';
+
+const CORNERS: BadgePosition[] = ['top-end', 'top-start', 'bottom-end', 'bottom-start'];
+
+/** On a corner of what it is in: `position` inside a button, or `Badge.attach` on any component (here a `<span>`). */
+export default function OnCorner() {
+  return (
+    <Stack orientation="horizontal" wrap align="center" gap="xl">
+      {CORNERS.map((corner) => (
+        <Button key={corner} text={corner} variant="outline">
+          <Badge count={7} position={corner} />
+        </Button>
+      ))}
+      <span ref={(bell) => Badge.attach(bell, { dot: true, tone: 'danger', label: 'New notifications' })}>Notifications</span>
+    </Stack>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { Badge, Stack, type ControlSize } from '@motifx-community/ui';
+
+const SIZES: ControlSize[] = ['sm', 'md', 'lg'];
+
+/** A badge and a dot in each size. */
+export default function Sizes() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <Stack key={size} orientation="horizontal" align="center">
+          <Badge text={size} size={size} />
+          <Badge count={42} size={size} variant="subtle" />
+          <Badge dot size={size} />
+        </Stack>
+      ))}
+    </>
+  );
+}
+```
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Text` | Read where it stands, as part of what it is in. |
+| `label` | With a label the badge is an image with that name (`role="img"`), so a count can say what it counts. |
+| `Dot` | Without a label a dot is hidden from screen readers (`aria-hidden`): give it one when it says something. |
+| `Colour` | The tone is never the only way something is said: pair a tone with a text or a label. |
+
+## Localization
+
+A count is written in the kit language (`uiLocale`), again when it changes: “1,234” in English, “1.234” in Turkish.
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-badge` | The badge. `data-tone`, `data-variant`, `data-size`, `data-position`, `data-dot`, `data-empty`. |
+| `.mx-badge-anchor` | What a badge on a corner sits on (`position: relative`). |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `badge.badge` | Unit: the badge, at rest (solid, standard), in each look and tone (`accent` … `danger`, `subtle-*`, `outline-*`) and as a `dot`. |
+| `badge.height.*, badge.dot-size.*, badge.font-size.*, badge.padding.*` | The badge and the dot per size. |
+| `badge.offset` | How far a badge on a corner sits in from it. |
+| `badge.tone, badge.variant` | The tone and look a badge takes when none is given. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `text` | `Bind<string>` | `''` | A short text; shown while there is no `count`. |
+| `count` | `Bind<number \| null>` | `null` | A count, written in the kit language; over `max` it shows `max+`. |
+| `max` | `Bind<number>` | `99` | The highest count written as it is. |
+| `showZero` | `Bind<boolean>` | `false` | A count of 0 shows; without it the badge hides at 0. |
+| `dot` | `Bind<boolean>` | `false` | A dot only: there is something, without saying what. |
+| `tone` | `Bind<BadgeTone>` | the language’s | `standard`, `accent`, `info`, `success`, `caution`, `danger`. Material marks counts in `danger`, the other languages in `accent`. |
+| `variant` | `Bind<BadgeVariant>` | the language’s (`solid`) | `solid`, `subtle`, `outline`. |
+| `size` | `Bind<ControlSize>` | `'md'` | `sm`, `md`, `lg`. |
+| `position` | `Bind<BadgePosition \| null>` | `null` | `top-end`, `top-start`, `bottom-end`, `bottom-start`: on that corner of what it is in, which becomes its anchor. `start` and `end` follow the writing direction. |
+| `label` | `Bind<string>` | `''` | What screen readers say (“3 unread messages”); without it they read the text. |
+| `visible, tabStop` | see Control |  | The shared properties of every control. |
+
+### Properties
+
+| Property | Access | Description |
+| --- | --- | --- |
+| `every prop above` | read/write | A value or a function, like the prop. |
+| `shownText` | read-only | What it shows now: the count as written (`99+`), else the text; `''` for a dot. |
+
+### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `Badge.attach(target, props?)` | `Badge` | Puts a badge on a corner of a component (`top-end` unless `props` says otherwise). It becomes one of its children and goes with it. |