@misoto22/kioku-ui 0.1.0 → 0.2.0

package/src/Layout/Layout.tsx

@@ -0,0 +1,190 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// The margin the page head hangs its numeral into. The scale has no name for
+// it, so it is built from the scale: one full step plus the row step, which
+// lands on the console's 2.4rem gutter at either density.
+const marginColumn = `calc(${semanticTokens.spacing2xl} + ${semanticTokens.spacingMd})`;
+
+// Hanging means the numeral goes into the margin and the title keeps the text
+// edge. The pull is exactly the page's own side margin — the same token
+// `content` spends on `paddingInline` — so the numeral comes to rest on the
+// paper's edge and never overhangs it. Change the margin and the hang follows.
+const hangColumn = `calc(${semanticTokens.spacing2xl} - ${semanticTokens.spacingSm})`;
+
+const styles = stylex.create({
+  frame: {
+    backgroundColor: semanticTokens.colorCanvas,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    minHeight: '100%',
+  },
+  body: {display: 'flex', flexGrow: 1, minHeight: 0},
+  rail: {flexShrink: 0},
+  // The trailing rail is the one region that carries no surface of its own, so
+  // the frame draws the rule that parts it from the content.
+  asideRail: {
+    borderInlineStartColor: semanticTokens.borderStrong,
+    borderInlineStartStyle: semanticTokens.borderStyle,
+    borderInlineStartWidth: semanticTokens.borderWidth,
+    flexShrink: 0,
+    paddingBlock: semanticTokens.spacingLg,
+    paddingInline: semanticTokens.spacingMd,
+  },
+  // The page's own margins. The side margin is a step wider than the head and
+  // foot, the way a printed page is set: the column of text wants more air
+  // beside it than above it, and the rail already supplies an edge on one side.
+  content: {
+    display: 'flex',
+    flexDirection: 'column',
+    flexGrow: 1,
+    minWidth: 0,
+    paddingBlock: semanticTokens.spacingXl,
+    paddingInline: semanticTokens.spacing2xl,
+    rowGap: semanticTokens.spacingXl,
+  },
+  flush: {paddingBlock: 0, paddingInline: 0, rowGap: 0},
+  // A chapter opening, not a stacked title. The numeral hangs in the margin
+  // the way a printed opening sets it — and it does so in the flow, because
+  // positioning it out of the flow makes it collide with the title the moment
+  // the column has room to centre itself.
+  pageHead: {
+    alignItems: 'baseline',
+    columnGap: semanticTokens.spacingSm,
+    display: 'grid',
+    gridTemplateColumns: 'minmax(0, 1fr)',
+  },
+  // The two-column grid this used to be pushed the *title* inward by the width
+  // of the numeral column plus the gap — 44px — so the head no longer began
+  // where the prose beneath it began. Pulling the whole grid back by the page
+  // margin puts the title on the text edge and sends the numeral out into the
+  // margin, which is the arrangement the comment above always described.
+  pageHeadIndexed: {
+    gridTemplateColumns: `${hangColumn} minmax(0, 1fr)`,
+    marginInlineStart: `calc(-1 * ${semanticTokens.spacing2xl})`,
+  },
+  // With the page margins off there is no margin to hang into, so the numeral
+  // takes a column in the flow rather than overhanging the frame.
+  pageHeadIndexedFlush: {
+    gridTemplateColumns: `${marginColumn} minmax(0, 1fr)`,
+    marginInlineStart: 0,
+  },
+  // Set in the display face and the third rank of ink: it is wayfinding, and
+  // a numeral drawn at the title's weight would compete with the title.
+  pageIndex: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeLg,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingHeading,
+    lineHeight: semanticTokens.lineHeightHeading,
+    marginBlock: 0,
+    marginInline: 0,
+    textAlign: 'end',
+  },
+  // The rule closes the chapter head across the measure the text occupies. It
+  // sits here rather than on the grid so that a hanging numeral stays outside
+  // it: a rule that ran under the numeral too would end 28px left of every
+  // other edge on the page.
+  pageHeadBody: {
+    borderBlockEndColor: semanticTokens.borderStrong,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: 0,
+    paddingBlockEnd: semanticTokens.spacingLg,
+    rowGap: semanticTokens.spacingXs,
+  },
+  footer: {
+    borderBlockStartColor: semanticTokens.borderStrong,
+    borderBlockStartStyle: semanticTokens.borderStyle,
+    borderBlockStartWidth: semanticTokens.borderWidth,
+    paddingBlock: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingLg,
+  },
+});
+
+/** Props for the page frame that positions banner, rails, and content. */
+export interface LayoutProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly aside?: ReactNode;
+  readonly children: ReactNode;
+  readonly contentPadding?: boolean;
+  readonly footer?: ReactNode;
+  readonly header?: ReactNode;
+  readonly mainId?: string;
+  readonly pageHead?: ReactNode;
+  readonly pageIndex?: ReactNode;
+  readonly sidebar?: ReactNode;
+}
+
+/**
+ * Positions the page regions. `children` is emitted as `main`, so a skip link
+ * has a landmark to reach and every page has exactly one main region.
+ *
+ * Set `contentPadding={false}` when the page supplies its own container; two
+ * layers of padding otherwise fight over the gutter. `mainId` lands on the
+ * `main` element itself, which is what a skip link must target — put it on
+ * the frame and the reader is dropped before the banner again.
+ *
+ * `pageHead` opens the main region with a chapter head rather than a flat
+ * stacked title, and `pageIndex` hangs a numeral in the margin beside it.
+ */
+export function Layout({
+  aside,
+  children,
+  contentPadding = true,
+  footer,
+  header,
+  mainId,
+  pageHead,
+  pageIndex,
+  sidebar,
+  ...props
+}: LayoutProps) {
+  return (
+    <div {...props} {...stylex.props(styles.frame)}>
+      {header}
+      <div {...stylex.props(styles.body)}>
+        {sidebar === undefined ? null : (
+          <div {...stylex.props(styles.rail)}>{sidebar}</div>
+        )}
+        <main
+          {...(mainId === undefined ? {} : {id: mainId})}
+          {...stylex.props(styles.content, !contentPadding && styles.flush)}
+        >
+          {pageHead === undefined ? null : (
+            <header
+              {...stylex.props(
+                styles.pageHead,
+                pageIndex !== undefined && styles.pageHeadIndexed,
+                pageIndex !== undefined &&
+                  !contentPadding &&
+                  styles.pageHeadIndexedFlush,
+              )}
+            >
+              {pageIndex === undefined ? null : (
+                <p {...stylex.props(styles.pageIndex)}>{pageIndex}</p>
+              )}
+              <div {...stylex.props(styles.pageHeadBody)}>{pageHead}</div>
+            </header>
+          )}
+          {children}
+        </main>
+        {aside === undefined ? null : (
+          <div {...stylex.props(styles.asideRail)}>{aside}</div>
+        )}
+      </div>
+      {footer === undefined ? null : (
+        <footer {...stylex.props(styles.footer)}>{footer}</footer>
+      )}
+    </div>
+  );
+}

package/src/Layout/index.ts

@@ -0,0 +1 @@
+export {Layout, type LayoutProps} from './Layout.js';

package/src/Lightbox/Lightbox.doc.ts

@@ -0,0 +1,20 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const lightboxDoc = {
+  name: 'Lightbox',
+  description: 'Shows one piece of media at viewport scale.',
+  props: [
+    {name: 'children', description: 'Supplies the media to show.'},
+    {name: 'closeLabel', description: 'Names the dismiss control.'},
+    {
+      name: 'onDismiss',
+      description: 'Runs on Escape, the scrim, or the control.',
+    },
+    {name: 'open', description: 'Controls whether the viewer renders.'},
+    {name: 'title', description: 'Names the media for assistive technology.'},
+  ],
+  inheritedProps: ['None; Lightbox owns its modal surface'],
+  example:
+    '<Lightbox onDismiss={close} open={open} title="Cover">{image}</Lightbox>',
+  storyId: 'core-lightbox--default',
+} satisfies ComponentDoc;

package/src/Lightbox/Lightbox.tsx

@@ -0,0 +1,114 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {scrolling} from '../scrolling/index.js';
+import {useInternationalization} from '../i18n/index.js';
+import {Icon} from '../Icon/index.js';
+import {IconButton} from '../IconButton/index.js';
+import {Overlay} from '../Overlay/index.js';
+
+const styles = stylex.create({
+  surface: {
+    backgroundColor: semanticTokens.colorSurfaceRaised,
+    borderRadius: semanticTokens.radiusContainer,
+    boxShadow: semanticTokens.elevationHigh,
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    maxHeight: '100%',
+    // Caption band over well, divided by a rule that reaches both edges.
+    overflow: 'hidden',
+  },
+  header: {
+    alignItems: 'center',
+    borderBlockEndColor: semanticTokens.borderDefault,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    gap: semanticTokens.spacingMd,
+    justifyContent: 'space-between',
+    paddingBlock: semanticTokens.spacingSm,
+    paddingInline: semanticTokens.spacingLg,
+  },
+  // An eyebrow, not a headline. The media is the subject of this surface and
+  // the caption only has to say which one it is.
+  title: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+    textTransform: 'uppercase',
+  },
+  // The media sits in a well rather than on the plate itself, so a picture
+  // with a pale edge still reads as a picture and not as part of the surface.
+  // The well runs to the surface edge; the surface clips its own corners.
+  media: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    display: 'flex',
+    justifyContent: 'center',
+    minHeight: 0,
+    overflow: 'auto',
+    padding: semanticTokens.spacingLg,
+  },
+});
+
+/** Props for a full-viewport media viewer. */
+export interface LightboxProps {
+  readonly children: ReactNode;
+  readonly closeLabel?: string;
+  readonly onDismiss: () => void;
+  readonly open: boolean;
+  readonly title: ReactNode;
+}
+
+/**
+ * Shows one piece of media at viewport scale. It is modal, so the page behind
+ * stops scrolling and focus stays on the media until it is dismissed.
+ */
+export function Lightbox({
+  children,
+  closeLabel,
+  onDismiss,
+  open,
+  title,
+}: LightboxProps) {
+  const {messages} = useInternationalization();
+  const titleId = useId();
+
+  return (
+    <Overlay onDismiss={onDismiss} open={open}>
+      <div
+        aria-labelledby={titleId}
+        aria-modal="true"
+        role="dialog"
+        {...stylex.props(styles.surface)}
+      >
+        <div {...stylex.props(styles.header)}>
+          <p id={titleId} {...stylex.props(styles.title)}>
+            {title}
+          </p>
+          <IconButton
+            aria-label={closeLabel ?? messages.close}
+            onClick={onDismiss}
+            variant="ghost"
+          >
+            <Icon>
+              <path
+                d="m6 6 12 12M18 6 6 18"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+              />
+            </Icon>
+          </IconButton>
+        </div>
+        <div {...stylex.props(styles.media, scrolling.region)}>{children}</div>
+      </div>
+    </Overlay>
+  );
+}

package/src/Lightbox/index.ts

@@ -0,0 +1 @@
+export {Lightbox, type LightboxProps} from './Lightbox.js';

package/src/List/List.doc.ts

@@ -0,0 +1,27 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const listDoc = {
+  name: 'List',
+  description: 'Groups related items with semantic list markup.',
+  props: [
+    {name: 'gap', description: 'Selects the space between items.'},
+    {
+      name: 'variant',
+      description: 'Selects the marker treatment and the underlying element.',
+    },
+  ],
+  inheritedProps: [
+    'OlHTMLAttributes<HTMLOListElement> and HTMLAttributes<HTMLUListElement> except className and type',
+  ],
+  example: '<List><ListItem>Draft</ListItem></List>',
+  storyId: 'core-list--default',
+} satisfies ComponentDoc;
+
+export const listItemDoc = {
+  name: 'ListItem',
+  description: 'Renders one entry inside a List.',
+  props: [{name: 'children', description: 'Supplies the entry content.'}],
+  inheritedProps: ['LiHTMLAttributes<HTMLLIElement> except className'],
+  example: '<ListItem>Ready to review</ListItem>',
+  storyId: 'core-list--default',
+} satisfies ComponentDoc;

package/src/List/List.tsx

@@ -0,0 +1,94 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, LiHTMLAttributes, OlHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {Space} from '../Stack/index.js';
+
+const styles = stylex.create({
+  base: {
+    color: semanticTokens.colorText,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    marginBlock: 0,
+  },
+  marked: {
+    paddingInlineStart: semanticTokens.spacingXl,
+  },
+  plain: {
+    listStyleType: 'none',
+    paddingInlineStart: 0,
+  },
+  unordered: {listStyleType: 'disc'},
+  ordered: {listStyleType: 'decimal'},
+  gapXs: {gap: semanticTokens.spacingXs},
+  gapSm: {gap: semanticTokens.spacingSm},
+  gapMd: {gap: semanticTokens.spacingMd},
+  gapLg: {gap: semanticTokens.spacingLg},
+  gapXl: {gap: semanticTokens.spacingXl},
+  gap2xl: {gap: semanticTokens.spacing2xl},
+  item: {marginBlock: 0},
+});
+
+const gaps = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+} as const;
+
+/** Marker treatments a list can apply to its items. */
+export type ListVariant = 'unordered' | 'ordered' | 'plain';
+
+/** Props for a vertical collection of related items. */
+export interface ListProps extends Omit<
+  OlHTMLAttributes<HTMLOListElement> & HTMLAttributes<HTMLUListElement>,
+  'className' | 'type'
+> {
+  readonly gap?: Space;
+  readonly variant?: ListVariant;
+}
+
+/**
+ * Renders a semantic list. `ordered` emits `ol` so reading order carries
+ * meaning; the other variants emit `ul`.
+ */
+export function List({
+  children,
+  gap = 'sm',
+  variant = 'unordered',
+  ...props
+}: ListProps) {
+  const listProps = {
+    ...props,
+    ...stylex.props(
+      styles.base,
+      gaps[gap],
+      variant === 'plain' ? styles.plain : styles.marked,
+      variant !== 'plain' && styles[variant],
+    ),
+  };
+
+  return variant === 'ordered' ? (
+    <ol {...listProps}>{children}</ol>
+  ) : (
+    <ul {...listProps}>{children}</ul>
+  );
+}
+
+/** Props for a single entry inside a `List`. */
+export type ListItemProps = Omit<LiHTMLAttributes<HTMLLIElement>, 'className'>;
+
+/** Renders one list entry without overriding the parent marker treatment. */
+export function ListItem({children, ...props}: ListItemProps) {
+  return (
+    <li {...props} {...stylex.props(styles.item)}>
+      {children}
+    </li>
+  );
+}

package/src/List/index.ts

@@ -0,0 +1,7 @@
+export {
+  List,
+  ListItem,
+  type ListItemProps,
+  type ListProps,
+  type ListVariant,
+} from './List.js';

package/src/Markdown/Markdown.doc.ts

@@ -0,0 +1,14 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const markdownDoc = {
+  name: 'Markdown',
+  description: 'Renders a restricted Markdown subset into system components.',
+  props: [
+    {name: 'source', description: 'Supplies the Markdown text to render.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and dangerouslySetInnerHTML',
+  ],
+  example: '<Markdown source="## Release 12\\n\\nReady to **publish**." />',
+  storyId: 'core-markdown--default',
+} satisfies ComponentDoc;

package/src/Markdown/Markdown.tsx

@@ -0,0 +1,115 @@
+import * as stylex from '@stylexjs/stylex';
+import {Fragment, type HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Blockquote} from '../Blockquote/index.js';
+import {Code} from '../Code/index.js';
+import {Heading} from '../Heading/index.js';
+import {List, ListItem} from '../List/index.js';
+import {Link} from '../navigation/index.js';
+import {Text} from '../Text/index.js';
+import {parseMarkdown, type InlineNode} from './parse.js';
+
+const styles = stylex.create({
+  prose: {
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingMd,
+  },
+  // Nothing rendered here leans on inheritance for its face. `em` and
+  // `strong` are the only elements this file draws itself, so they name the
+  // family they are set in. Neither sets a size, so neither sets tracking:
+  // an emphasised run keeps whatever the block around it was opened to.
+  emphasis: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontStyle: 'italic',
+  },
+  strong: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontStyle: 'normal',
+    fontWeight: semanticTokens.fontWeightStrong,
+  },
+});
+
+function renderInline(spans: readonly InlineNode[]) {
+  return spans.map((span, index) => {
+    switch (span.kind) {
+      case 'code':
+        return <Code key={index}>{span.text}</Code>;
+      case 'emphasis':
+        return (
+          <em key={index} {...stylex.props(styles.emphasis)}>
+            {span.text}
+          </em>
+        );
+      case 'link':
+        return (
+          <Link href={span.href} key={index}>
+            {span.text}
+          </Link>
+        );
+      case 'strong':
+        return (
+          <strong key={index} {...stylex.props(styles.strong)}>
+            {span.text}
+          </strong>
+        );
+      default:
+        return <Fragment key={index}>{span.text}</Fragment>;
+    }
+  });
+}
+
+/** Props for rendering a restricted Markdown subset. */
+export interface MarkdownProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'dangerouslySetInnerHTML'
+> {
+  readonly source: string;
+}
+
+/**
+ * Renders a deliberately small Markdown subset into system components. Raw
+ * HTML is never interpreted and only http(s) or root-relative links survive,
+ * so text from an untrusted source cannot inject markup or a script URL.
+ */
+export function Markdown({source, ...props}: MarkdownProps) {
+  const blocks = parseMarkdown(source);
+
+  return (
+    <div {...props} {...stylex.props(styles.prose)}>
+      {blocks.map((block, index) => {
+        switch (block.kind) {
+          case 'heading':
+            return (
+              <Heading
+                key={index}
+                level={block.level}
+                size={block.level === 2 ? 'section' : 'subsection'}
+              >
+                {renderInline(block.spans)}
+              </Heading>
+            );
+          case 'list':
+            return (
+              <List
+                key={index}
+                variant={block.ordered ? 'ordered' : 'unordered'}
+              >
+                {block.items.map((item, itemIndex) => (
+                  <ListItem key={itemIndex}>{renderInline(item)}</ListItem>
+                ))}
+              </List>
+            );
+          case 'quote':
+            return (
+              <Blockquote key={index}>{renderInline(block.spans)}</Blockquote>
+            );
+          default:
+            return <Text key={index}>{renderInline(block.spans)}</Text>;
+        }
+      })}
+    </div>
+  );
+}

package/src/Markdown/index.ts

@@ -0,0 +1,7 @@
+export {Markdown, type MarkdownProps} from './Markdown.js';
+export {
+  parseInline,
+  parseMarkdown,
+  type BlockNode,
+  type InlineNode,
+} from './parse.js';