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

package/docs/calendar.md

@@ -0,0 +1,136 @@
+# Calendar
+
+> Editors · @motifx-community/ui 0.1.0-beta.0
+
+A month of days to pick a date from, with a year and a decade view to get far quickly. It is the picker of DateBox, and it works on its own.
+
+## Import
+
+```tsx
+import { Calendar } from '@motifx-community/ui';
+```
+
+## From JSX and from code
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Calendar, Stack } from '@motifx-community/ui';
+
+/** A calendar bound with x-model, and calendars created with `new`, added from code and moved to a month. */
+export default function FromCode() {
+  const form = reactive({ day: new Date() as Date | null, result: '' });
+  let host: Stack | null = null;
+
+  const addFromCode = () => {
+    const calendar = new Calendar({ locale: 'tr-TR' });
+    calendar.onValueChanged((e) => (form.result = e.value ? e.value.toDateString() : '—'));
+    host?.controls.add(calendar);
+    calendar.goTo(new Date(2027, 0, 1));
+  };
+
+  return (
+    <>
+      <Calendar x-model={() => form.day} showWeekNumbers showTodayButton />
+      <output class="cal-day">{() => (form.day ? form.day.toDateString() : '—')}</output>
+      <Button text="Add a calendar from code" variant="outline" onclick={addFromCode} />
+      <output class="cal-made">{() => form.result}</output>
+      <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
+    </>
+  );
+}
+```
+
+## Limits
+
+```tsx
+import { Calendar } from '@motifx-community/ui';
+
+/** No day before today and no Sunday, in Turkish. */
+export default function Limits() {
+  return <Calendar min={new Date()} disabledDates={(d: Date) => d.getDay() === 0} locale="tr-TR" />;
+}
+```
+
+## Views
+
+The title zooms out to the months of the year and to twelve years; a choice there zooms back in. `minView` makes a month or a year the choice itself.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Calendar, Stack, type CalendarView } from '@motifx-community/ui';
+
+const views: CalendarView[] = ['month', 'year', 'decade'];
+
+/** The view set from state, and a calendar whose choice is a month. */
+export default function Views() {
+  const s = reactive({ view: 'month' as CalendarView, month: null as Date | null });
+  return (
+    <>
+      <Stack orientation="horizontal" wrap align="center" role="group" aria-label="View">
+        {views.map((view) => (
+          <Button key={view} text={view} size="sm" variant={() => (s.view === view ? 'solid' : 'ghost')} aria-pressed={() => s.view === view} onclick={() => (s.view = view)} />
+        ))}
+      </Stack>
+      <Calendar currentView={() => s.view} />
+      <Calendar minView="year" x-model={() => s.month} />
+      <output>{() => (s.month ? s.month.toLocaleDateString(undefined, { month: 'long', year: 'numeric' }) : '—')}</output>
+    </>
+  );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Left / Right` | The day before / after (mirrored right to left); a month or a year in the other views. |
+| `Up / Down` | The same day a week before / after; four months or years in the other views. |
+| `Home / End` | The first / last day of the week; the start / end of the row in the other views. |
+| `Page Up / Page Down` | The month before / after; with Shift, the year. A year, a decade in the other views. |
+| `Enter, Space` | Choose the day; in the other views, open the month or the year. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Pattern` | The APG date picker grid: `role="grid"`, one Tab stop on the focused day, the arrows inside. |
+| `Cells` | Each day is named in full ("Sunday, 25 October 2026"); `aria-selected`, `aria-current="date"` for today, `aria-disabled`. |
+| `Header` | Weekday names have their full form in `abbr`; the title is a live region, so a new month is read out. |
+| `Buttons` | Previous / next are named from `uiLocale` for the view on screen. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-calendar` | `data-view="month\|year\|decade"`. |
+| `.mx-calendar__header, __previous, __title, __next` | The header. |
+| `.mx-calendar__cell` | `aria-selected`, `aria-disabled`, `data-today`, `data-outside`. |
+| `calendar.container, header, title, nav, nav-icon, weekday, week, cell, ring, foot, today` | Units: every piece in its states (a cell: `block`, `hover`, `pressed`, `focus`, `outside`, `today`, `selected`, `disabled` …). |
+| `calendar.day-size, calendar.view-cell-width-scale, calendar.view-cell-height-scale, calendar.previous-rotate, calendar.next-rotate` | A day's size (the grid is built on it), the zoomed-out views' cells, the arrows' turns. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<Date \| null>` | `null` | The chosen date. `x-model` binds it two-way. |
+| `min / max` | `Bind<Date \| null>` | — | Days outside cannot be chosen; the arrows stop there. |
+| `disabledDates` | `Bind<(date) => boolean>` | — | Days that cannot be chosen. |
+| `locale` | `Bind<string>` | the page's | Month and day names, and where weeks start. |
+| `firstDayOfWeek` | `Bind<number \| null>` | the locale’s | 0 Sunday … 6 Saturday. |
+| `showWeekNumbers` | `Bind<boolean>` | `false` | ISO week numbers before each week. |
+| `showOtherMonths` | `Bind<boolean>` | `true` | Days of the months before and after. |
+| `showTodayButton` | `Bind<boolean>` | `false` | A Today button under the grid. |
+| `currentView` | `Bind<'month' \| 'year' \| 'decade'>` | `'month'` | The view on screen; the title zooms out, a choice zooms in. |
+| `minView` | `Bind<CalendarView>` | `'month'` | The view a choice is made in: `year` picks a month, `decade` a year. |
+
+### Properties, methods, events
+
+| Member | Description |
+| --- | --- |
+| `focusedDate` | The day with the Tab stop; its month is on screen. |
+| `goTo(date)` | Shows the month of a date. |
+| `canChoose(date)` | Whether a day can be chosen. |
+| `focus()` | Focuses the day with the Tab stop. |
+| `onValueChanged(e)` | `{ value, previousValue, byUser, source, event? }`. |

package/docs/card.md

@@ -0,0 +1,254 @@
+# Card
+
+> Display · @motifx-community/ui 0.1.0-beta.0
+
+A surface holding one thing: a picture, a header with an avatar and titles, content and a row of actions. Parts with nothing in them are left out.
+
+## Import
+
+```tsx
+import { Card } 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 { Button, Card, Stack } from '@motifx-community/ui';
+
+/** A card from JSX follows its functions; one made with `new` takes the same properties from code. */
+export default function FromCode() {
+  const s = reactive({ following: false });
+  const coded = new Card({ title: 'Made in code', subtitle: 'new Card({ … })', variant: 'outline' });
+
+  return (
+    <Stack orientation="horizontal" wrap align="start" gap="lg">
+      <Card
+        title="Ada Lovelace"
+        subtitle={() => (s.following ? 'Following' : 'Mathematician')}
+        avatar={{ name: 'Ada Lovelace' }}
+        footer={<Button text={() => (s.following ? 'Unfollow' : 'Follow')} onclick={() => (s.following = !s.following)} />}
+        style="inline-size: 18rem"
+      >
+        First to publish an algorithm meant to be carried out by a machine.
+      </Card>
+      <span onConfig={(c) => c.controls.add(coded)} />
+    </Stack>
+  );
+}
+```
+
+## Looks
+
+```tsx
+import { Button, Card, Stack, type CardVariant } from '@motifx-community/ui';
+
+const VARIANTS: CardVariant[] = ['elevated', 'filled', 'outline'];
+
+/** Each look with a header, content and actions. */
+export default function Variants() {
+  return (
+    <Stack orientation="horizontal" wrap align="start" gap="lg">
+      {VARIANTS.map((variant) => (
+        <Card
+          key={variant}
+          variant={variant}
+          title={variant}
+          subtitle="A card of this look"
+          footer={
+            <Stack orientation="horizontal" gap="sm">
+              <Button text="Cancel" variant="ghost" />
+              <Button text="Open" />
+            </Stack>
+          }
+          style="inline-size: 16rem"
+        >
+          The same header, content and actions in each look.
+        </Card>
+      ))}
+    </Stack>
+  );
+}
+```
+
+## Pictures
+
+```tsx
+import { Button, Card, Stack } from '@motifx-community/ui';
+import { PICTURE } from './picture';
+
+/** A picture above the rest, or at its start (`horizontal`); it runs to the card's edges and takes its corners. */
+export default function Media() {
+  return (
+    <Stack orientation="horizontal" wrap align="start" gap="lg">
+      <Card media={PICTURE} mediaAlt="A sunset over a field" title="Sunset" subtitle="Above the rest" style="inline-size: 16rem">
+        The picture runs to the edges.
+      </Card>
+      <Card
+        media={PICTURE}
+        orientation="horizontal"
+        title="Sunset"
+        subtitle="At the start"
+        footer={<Button text="Save" variant="outline" />}
+        style="inline-size: 24rem"
+      >
+        As tall as the card.
+      </Card>
+    </Stack>
+  );
+}
+```
+
+## Clickable
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Card, Stack } from '@motifx-community/ui';
+
+const PLACES = ['Istanbul', 'Lisbon', 'Kyoto'];
+
+/** The whole card can be pressed: with the mouse, Enter or Space. */
+export default function Clickable() {
+  const s = reactive({ chosen: '' });
+
+  return (
+    <Stack gap="lg">
+      <Stack orientation="horizontal" wrap align="start">
+        {PLACES.map((place) => (
+          <Card key={place} title={place} subtitle="Press to choose" clickable onclick={() => (s.chosen = place)} style="inline-size: 12rem" />
+        ))}
+      </Stack>
+      <span>{() => (s.chosen ? `Chosen: ${s.chosen}` : 'Nothing chosen yet')}</span>
+    </Stack>
+  );
+}
+```
+
+## Links and selection
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Card, Stack } from '@motifx-community/ui';
+
+const PLACES = ['Istanbul', 'Lisbon', 'Kyoto'];
+
+/**
+ * A link card: its title is the link and a press anywhere on it follows it (`rel="router"` hands it to the router);
+ * its own button stays a button. A selectable card turns on and off with a press or its check box.
+ */
+export default function Links() {
+  const s = reactive({ picked: [] as string[] });
+  const toggle = (place: string, on: boolean) => {
+    s.picked = on ? [...s.picked, place] : s.picked.filter((p) => p !== place);
+  };
+
+  return (
+    <Stack gap="lg">
+      <Stack orientation="horizontal" wrap align="start">
+        <Card title="Tokens" subtitle="A link to the tokens page" href="/tokens" rel="router" footer={<Button text="Later" variant="ghost" />} style="inline-size: 14rem" />
+        <Card title="Keyboard" subtitle="A link to the keyboard page" href="/keyboard" rel="router" style="inline-size: 14rem" />
+      </Stack>
+      <Stack orientation="horizontal" wrap align="start">
+        {PLACES.map((place) => (
+          <Card
+            key={place}
+            title={place}
+            subtitle="Press to pick"
+            selectable
+            selected={() => s.picked.includes(place)}
+            onSelectedChanged={(e) => e.byUser && toggle(place, e.selected)}
+            style="inline-size: 12rem"
+          />
+        ))}
+      </Stack>
+      <span>{() => `Picked: ${s.picked.join(', ') || 'none'}`}</span>
+    </Stack>
+  );
+}
+```
+
+## Sizes
+
+```tsx
+import { Card, Stack, type ControlSize } from '@motifx-community/ui';
+
+const SIZES: ControlSize[] = ['sm', 'md', 'lg'];
+
+/** The space in and between the parts, per size. */
+export default function Sizes() {
+  return (
+    <Stack orientation="horizontal" wrap align="start" gap="lg">
+      {SIZES.map((size) => (
+        <Card key={size} size={size} title={`Size ${size}`} subtitle="Grace Hopper" avatar={{ name: 'Grace Hopper' }} style="inline-size: 15rem">
+          Content of the card.
+        </Card>
+      ))}
+    </Stack>
+  );
+}
+```
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Name` | A `group` named by its title (`aria-labelledby`). |
+| `Picture` | Adorns unless `mediaAlt` says what it shows. |
+| `Clickable` | A Tab stop; Enter and Space press it. Buttons inside it stay buttons of their own. |
+| `Link` | The title is a real link (read and followed as one); the card shows its focus. The card’s own buttons stay above it. |
+| `Selectable` | A check box named “Select <title>” in the kit language; the card shows the selection with its frame. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-card` | The card. `data-variant`, `data-size`, `data-orientation`, `data-pressable`, `data-disabled`. |
+| `.mx-card__media` | The picture. |
+| `.mx-card__body` | Header, content and actions. |
+| `.mx-card__header, .mx-card__avatar, .mx-card__heading, .mx-card__title, .mx-card__subtitle, .mx-card__action` | The header and its parts. |
+| `.mx-card__content, .mx-card__footer` | The content, and the row of actions. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `card.card` | Unit: the card at rest, then `elevated`, `filled`, `outline`, `selected`, `hover`, `pressed`, `focus`, `disabled`. |
+| `card.title, card.subtitle, card.content` | Units: the title, the line under it, the content’s text. |
+| `card.padding.*, card.gap.*` | The space around and between the parts, per size. |
+| `card.header-gap, card.footer-gap, card.media-width` | The space in the header and between actions; the picture’s width at the start. |
+| `card.variant, card.footer-align` | The look a card takes when none is given; where the actions sit (Fluent: at the start, the others: at the end). |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `Bind<string>` | `''` | The title; it names the card for screen readers. |
+| `subtitle` | `Bind<string>` | `''` | The line under the title. |
+| `avatar` | `Bind<AvatarProps \| null>` | `null` | An avatar before the titles (its props). |
+| `action` | `Bind<ComponentBase \| null>` | `null` | Something at the end of the header: a menu button, a badge. |
+| `media` | `Bind<IconSource \| null>` | `null` | A picture running to the card’s edges: an image address, an element or a component. |
+| `mediaAlt` | `Bind<string>` | `''` | What the picture shows, for screen readers, when `media` is an image address. Without it the picture only adorns. |
+| `content` | `Bind<ComponentBase \| null>` | `null` | What fills the content, besides JSX children. |
+| `footer` | `Bind<ComponentBase \| null>` | `null` | A row of actions under the content. A component replaced leaves the card and stays yours. |
+| `variant` | `Bind<CardVariant>` | the language’s (`elevated`) | `elevated`, `filled`, `outline`. |
+| `size` | `Bind<ControlSize>` | `'md'` | The space in and between the parts: `sm`, `md`, `lg`. |
+| `orientation` | `Bind<CardOrientation>` | `'vertical'` | `horizontal` puts the picture at the start. |
+| `clickable` | `Bind<boolean>` | `false` | The whole card can be pressed (`onclick`, Enter, Space). |
+| `href` | `Bind<string \| null>` | `null` | The whole card is a link there: its title is the link, and a press anywhere on the card follows it. |
+| `rel` | `Bind<string>` | `''` | The link’s `rel`; `router` lets the MotifJS router take it. |
+| `selectable` | `Bind<boolean>` | `false` | A check box on its top end corner; a press on the card turns it on and off. |
+| `selected` | `Bind<boolean>` | `false` | Whether it is selected. |
+| `onSelectedChanged` | `CardSelectedChangedEventArgs` |  | It was selected or not any more (`selected`), by the user or by code (`byUser`). |
+| `enabled, 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. |
+| `contentPart` | read-only | The part holding the content, for adding to it from code. |
+| `avatarControl` | read-only | The avatar before the titles, when it has one. |