@korzun/design 0.0.6 → 0.2.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.
Files changed (89) hide show
  1. package/AGENTS.md +11 -4
  2. package/dist/component/heading/index.d.ts +303 -0
  3. package/dist/component/heading/index.d.ts.map +1 -0
  4. package/dist/component/heading/index.js +21 -0
  5. package/dist/component/heading/index.js.map +1 -0
  6. package/dist/component/heading/style.d.ts +5 -0
  7. package/dist/component/heading/style.d.ts.map +1 -0
  8. package/dist/component/heading/style.js +5 -0
  9. package/dist/component/heading/style.js.map +1 -0
  10. package/dist/component/index.d.ts +4 -0
  11. package/dist/component/index.d.ts.map +1 -1
  12. package/dist/component/index.js +4 -0
  13. package/dist/component/index.js.map +1 -1
  14. package/dist/component/inline/index.d.ts +303 -0
  15. package/dist/component/inline/index.d.ts.map +1 -0
  16. package/dist/component/inline/index.js +13 -0
  17. package/dist/component/inline/index.js.map +1 -0
  18. package/dist/component/inline/style.d.ts +5 -0
  19. package/dist/component/inline/style.d.ts.map +1 -0
  20. package/dist/component/inline/style.js +18 -0
  21. package/dist/component/inline/style.js.map +1 -0
  22. package/dist/component/stack/gap.d.ts +4 -0
  23. package/dist/component/stack/gap.d.ts.map +1 -0
  24. package/dist/component/stack/gap.js +10 -0
  25. package/dist/component/stack/gap.js.map +1 -0
  26. package/dist/component/stack/index.d.ts +299 -0
  27. package/dist/component/stack/index.d.ts.map +1 -0
  28. package/dist/component/stack/index.js +13 -0
  29. package/dist/component/stack/index.js.map +1 -0
  30. package/dist/component/stack/style.d.ts +5 -0
  31. package/dist/component/stack/style.d.ts.map +1 -0
  32. package/dist/component/stack/style.js +12 -0
  33. package/dist/component/stack/style.js.map +1 -0
  34. package/dist/component/tag/index.d.ts +1 -1
  35. package/dist/component/tag/index.d.ts.map +1 -1
  36. package/dist/component/tag/index.js.map +1 -1
  37. package/dist/component/tag/style.d.ts +1 -1
  38. package/dist/component/tag/style.d.ts.map +1 -1
  39. package/dist/component/text/index.d.ts +307 -0
  40. package/dist/component/text/index.d.ts.map +1 -0
  41. package/dist/component/text/index.js +15 -0
  42. package/dist/component/text/index.js.map +1 -0
  43. package/dist/component/text/style.d.ts +11 -0
  44. package/dist/component/text/style.d.ts.map +1 -0
  45. package/dist/component/text/style.js +48 -0
  46. package/dist/component/text/style.js.map +1 -0
  47. package/dist/control/index.d.ts +1 -1
  48. package/dist/control/index.d.ts.map +1 -1
  49. package/dist/control/index.js +1 -1
  50. package/dist/control/index.js.map +1 -1
  51. package/dist/control/popover/index.d.ts +24 -8
  52. package/dist/control/popover/index.d.ts.map +1 -1
  53. package/dist/control/popover/index.js +60 -15
  54. package/dist/control/popover/index.js.map +1 -1
  55. package/dist/control/popover/position.d.ts +47 -0
  56. package/dist/control/popover/position.d.ts.map +1 -0
  57. package/dist/control/popover/position.js +29 -0
  58. package/dist/control/popover/position.js.map +1 -0
  59. package/dist/theme/theme.d.ts +25 -0
  60. package/dist/theme/theme.d.ts.map +1 -1
  61. package/dist/theme/theme.js +43 -1
  62. package/dist/theme/theme.js.map +1 -1
  63. package/docs/component/heading.md +85 -0
  64. package/docs/component/inline.md +64 -0
  65. package/docs/component/meta-line.md +13 -17
  66. package/docs/component/metadata-list.md +1 -1
  67. package/docs/component/stack.md +68 -0
  68. package/docs/component/tag.md +26 -6
  69. package/docs/component/text.md +94 -0
  70. package/docs/control/popover.md +41 -10
  71. package/docs/patterns.md +28 -9
  72. package/docs/theme.md +10 -9
  73. package/docs/tokens.md +4 -4
  74. package/package.json +1 -1
  75. package/src/component/heading/index.tsx +64 -0
  76. package/src/component/heading/style.ts +5 -0
  77. package/src/component/index.ts +4 -0
  78. package/src/component/inline/index.tsx +57 -0
  79. package/src/component/inline/style.ts +18 -0
  80. package/src/component/stack/gap.ts +16 -0
  81. package/src/component/stack/index.tsx +49 -0
  82. package/src/component/stack/style.ts +12 -0
  83. package/src/component/tag/index.tsx +1 -1
  84. package/src/component/text/index.tsx +61 -0
  85. package/src/component/text/style.ts +67 -0
  86. package/src/control/index.ts +6 -1
  87. package/src/control/popover/index.tsx +77 -19
  88. package/src/control/popover/position.ts +66 -0
  89. package/src/theme/theme.ts +59 -2
package/docs/tokens.md CHANGED
@@ -14,11 +14,11 @@ Surfaces, text, borders and state colours, mode-aware. Keys are grouped as follo
14
14
  - `color.text`: `primary secondary muted faint onPrimary onDanger description`
15
15
  - `color.bg`: `page card cardHeader track input footer glass glassFallback glassActive selected hover success placeholder`. `track` must read against both `page` and `card`; `hover` is a translucent scrim; `glass*` feed `recipe.glass`.
16
16
  - `color.border`: `default strong light focus hover danger glass glassActive faint loading success section`
17
- - `color.success`: a single value.
17
+ - `color.success`, `color.warning`, `color.info`: a single value each.
18
18
  - `color.brand`: `default hover active light outline loading loadingHover loadingActive linkHover`
19
19
  - `color.danger`: `default hover active light outline loading loadingHover loadingActive`
20
20
  - `color.overlay`: `backdrop`
21
- - `color.chip`: eight tinted label colourways, each `{ text, bg, border }`: `status author series subject book entryType user rating`. See Slated for curation.
21
+ - `color.chip`: thirteen tinted colourways, each `{ text, bg, border }`. Status tones: `success warning danger info neutral`. Label tones: `status author series subject book entryType user rating` (the `status` label tone is not a status tone). See Slated for curation.
22
22
 
23
23
  ## space
24
24
 
@@ -46,7 +46,7 @@ Two stacks: `body` (`system-ui, sans-serif`) and `mono`.
46
46
 
47
47
  ## fontWeight
48
48
 
49
- Numeric weights: `medium semibold bold extrabold` (500, 600, 700, 800).
49
+ Numeric weights: `regular medium semibold bold extrabold` (400, 500, 600, 700, 800).
50
50
 
51
51
  ## lineHeight
52
52
 
@@ -90,7 +90,7 @@ JSS-spreadable style fragments (`...theme.recipe.x`), not components.
90
90
 
91
91
  Both groups below move into the package byte-for-byte in 0.0.1 and are due for a decision before the API settles.
92
92
 
93
- - `color.chip.*`: eight colourways (`status author series subject book entryType user rating`) named after Bookplate's metadata chips, not after a general role.
93
+ - `color.chip.*`: the eight label colourways (`status author series subject book entryType user rating`) are named after Bookplate's metadata chips, not after a general role.
94
94
  - `size.metadataValue`: `15rem`, a width named after Bookplate's metadata display.
95
95
 
96
96
  No other token name or comment in `src/theme/theme.ts` is clearly Bookplate-specific. Two comments mention app internals (`floatingControlTopBase` refers to the admin picker and `router/nav-layout-style`), but the tokens themselves are generic.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@korzun/design",
3
- "version": "0.0.6",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "repository": {
@@ -0,0 +1,64 @@
1
+ import cx from 'classnames';
2
+ import type { HTMLAttributes, ReactNode, Ref } from 'react';
3
+ import { createElement } from 'react';
4
+
5
+ import { useTypography, type TextSize, type TextTone, type TextWeight } from '../text/style.js';
6
+ import { useStyle } from './style.js';
7
+
8
+ const LEVELS = {
9
+ 1: { size: 'xxl', weight: 'bold' },
10
+ 2: { size: 'xl', weight: 'bold' },
11
+ 3: { size: 'lg', weight: 'semibold' },
12
+ 4: { size: 'md', weight: 'semibold' },
13
+ } as const satisfies Record<1 | 2 | 3 | 4, { size: TextSize; weight: TextWeight }>;
14
+
15
+ export interface HeadingProps extends Omit<HTMLAttributes<HTMLHeadingElement>, 'style'> {
16
+ /** The heading level, rendered as `h1` to `h4`. Sets the default size and weight. */
17
+ level: 1 | 2 | 3 | 4;
18
+ /** Font size, from the theme's `fontSize` tokens. Default follows `level`: 1 `xxl`, 2 `xl`, 3 `lg`, 4 `md`. */
19
+ size?: TextSize;
20
+ /** Text colour. Default `'primary'`. */
21
+ tone?: TextTone;
22
+ /** Font weight, from the theme's `fontWeight` tokens. Default follows `level`: 1 and 2 `bold`, 3 and 4 `semibold`. */
23
+ weight?: TextWeight;
24
+ /** Clip to one line with an ellipsis. Default `false`. */
25
+ truncate?: boolean;
26
+ /** Extra class on the root. Override with `'&&'` specificity, never `!important`. */
27
+ className?: string;
28
+ /** The heading text. */
29
+ children?: ReactNode;
30
+ /** Ref to the root element. */
31
+ ref?: Ref<HTMLHeadingElement>;
32
+ }
33
+
34
+ /** A heading: `level` picks the element and a default look, props override the look. */
35
+ export const Heading = ({
36
+ level,
37
+ size,
38
+ tone = 'primary',
39
+ weight,
40
+ truncate = false,
41
+ className,
42
+ children,
43
+ ref,
44
+ ...rest
45
+ }: HeadingProps) => {
46
+ const style = useStyle();
47
+ const type = useTypography();
48
+ return createElement(
49
+ `h${level}`,
50
+ {
51
+ ...rest,
52
+ ref,
53
+ className: cx(
54
+ style.root,
55
+ type[`size-${size ?? LEVELS[level].size}`],
56
+ type[`tone-${tone}`],
57
+ type[`weight-${weight ?? LEVELS[level].weight}`],
58
+ truncate && type.truncate,
59
+ className
60
+ ),
61
+ },
62
+ children
63
+ );
64
+ };
@@ -0,0 +1,5 @@
1
+ import { createUseStyles, type Theme } from '../../theme/index.js';
2
+
3
+ export const useStyle = createUseStyles((theme: Theme) => ({
4
+ root: { margin: 0, lineHeight: theme.lineHeight.tight },
5
+ }));
@@ -3,6 +3,8 @@ export { CardDivider, type CardDividerAlign, type CardDividerProps } from './car
3
3
  export { CardRow, type CardRowProps } from './card-row/index.js';
4
4
  export { CollapsibleSection, type CollapsibleSectionProps } from './collapsible-section/index.js';
5
5
  export { EmptyState, type EmptyStateProps } from './empty-state/index.js';
6
+ export { Heading, type HeadingProps } from './heading/index.js';
7
+ export { Inline, type InlineProps } from './inline/index.js';
6
8
  export { MetaLine, type MetaLineProps } from './meta-line/index.js';
7
9
  export { MetadataList, type Metadata, type MetadataListProps } from './metadata-list/index.js';
8
10
  export { NavDesktop, type NavDesktopProps } from './nav-desktop/index.js';
@@ -10,6 +12,8 @@ export { NavMobile, type NavMobileProps, type NavPill } from './nav-mobile/index
10
12
  export type { NavItem } from './nav-types.js';
11
13
  export { Page, type PageProps, type PageTypeValue } from './page/index.js';
12
14
  export { ProgressIndicator, type ProgressIndicatorProps } from './progress-indicator/index.js';
15
+ export { Stack, type StackProps } from './stack/index.js';
13
16
  export { Tag, type TagProps, type TagTone } from './tag/index.js';
17
+ export { Text, type TextProps } from './text/index.js';
14
18
  export { ThemeSetting, type ThemeSettingProps } from './theme-setting/index.js';
15
19
  export { TopFade, type TopFadeProps } from './top-fade/index.js';
@@ -0,0 +1,57 @@
1
+ import cx from 'classnames';
2
+ import type { HTMLAttributes, ReactNode, Ref } from 'react';
3
+ import { createElement } from 'react';
4
+
5
+ import type { Gap } from '../stack/gap.js';
6
+ import { useStyle } from './style.js';
7
+
8
+ export interface InlineProps extends Omit<HTMLAttributes<HTMLElement>, 'style'> {
9
+ /** The element to render. `ul`/`ol` also reset list margin, padding and bullets. Default `'div'`. */
10
+ as?: 'div' | 'span' | 'ul' | 'ol' | 'li' | 'nav';
11
+ /** Space between children, from the theme's `space` tokens, or `'none'`. Default `'sm'`. */
12
+ gap?: Gap;
13
+ /** Cross-axis (vertical) alignment of children. Default `'center'`. */
14
+ align?: 'center' | 'start' | 'end' | 'baseline' | 'stretch';
15
+ /** Main-axis (horizontal) distribution. `'between'` pushes the first and last child to opposite edges. Default `'start'`. */
16
+ justify?: 'start' | 'center' | 'end' | 'between';
17
+ /** Let children wrap onto further lines instead of overflowing. Default `false`. */
18
+ wrap?: boolean;
19
+ /** Extra class on the root. Override with `'&&'` specificity, never `!important`. */
20
+ className?: string;
21
+ /** The children, laid out left to right. */
22
+ children?: ReactNode;
23
+ /** Ref to the root element. */
24
+ ref?: Ref<HTMLElement>;
25
+ }
26
+
27
+ /** Lays children out in a horizontal row with a themed gap between them. */
28
+ export const Inline = ({
29
+ as = 'div',
30
+ gap = 'sm',
31
+ align = 'center',
32
+ justify = 'start',
33
+ wrap = false,
34
+ className,
35
+ children,
36
+ ref,
37
+ ...rest
38
+ }: InlineProps) => {
39
+ const style = useStyle();
40
+ return createElement(
41
+ as,
42
+ {
43
+ ...rest,
44
+ ref,
45
+ className: cx(
46
+ style.root,
47
+ style[`gap-${gap}`],
48
+ style[`align-${align}`],
49
+ style[`justify-${justify}`],
50
+ wrap && style.wrap,
51
+ (as === 'ul' || as === 'ol') && style.list,
52
+ className
53
+ ),
54
+ },
55
+ children
56
+ );
57
+ };
@@ -0,0 +1,18 @@
1
+ import { createUseStyles, type Theme } from '../../theme/index.js';
2
+ import { gapRules } from '../stack/gap.js';
3
+
4
+ export const useStyle = createUseStyles((theme: Theme) => ({
5
+ root: { display: 'flex', flexDirection: 'row', minWidth: 0 },
6
+ list: { margin: 0, padding: 0, listStyle: 'none' },
7
+ wrap: { flexWrap: 'wrap' },
8
+ 'align-start': { alignItems: 'flex-start' },
9
+ 'align-center': { alignItems: 'center' },
10
+ 'align-end': { alignItems: 'flex-end' },
11
+ 'align-baseline': { alignItems: 'baseline' },
12
+ 'align-stretch': { alignItems: 'stretch' },
13
+ 'justify-start': { justifyContent: 'flex-start' },
14
+ 'justify-center': { justifyContent: 'center' },
15
+ 'justify-end': { justifyContent: 'flex-end' },
16
+ 'justify-between': { justifyContent: 'space-between' },
17
+ ...gapRules(theme),
18
+ }));
@@ -0,0 +1,16 @@
1
+ import type { Theme } from '../../theme/index.js';
2
+
3
+ export type Gap = keyof Theme['space'] | 'none';
4
+
5
+ // One static class per space token (shared by Stack and Inline), so a gap is a
6
+ // class swap rather than a per-instance dynamic style sheet.
7
+ export const gapRules = (theme: Theme) =>
8
+ ({
9
+ ...Object.fromEntries(
10
+ (Object.keys(theme.space) as (keyof Theme['space'])[]).map((key) => [
11
+ `gap-${key}`,
12
+ { gap: theme.space[key] },
13
+ ])
14
+ ),
15
+ 'gap-none': { gap: 0 },
16
+ }) as Record<`gap-${Gap}`, object>;
@@ -0,0 +1,49 @@
1
+ import cx from 'classnames';
2
+ import type { HTMLAttributes, ReactNode, Ref } from 'react';
3
+ import { createElement } from 'react';
4
+
5
+ import type { Gap } from './gap.js';
6
+ import { useStyle } from './style.js';
7
+
8
+ export interface StackProps extends Omit<HTMLAttributes<HTMLElement>, 'style'> {
9
+ /** The element to render. `ul`/`ol` also reset list margin, padding and bullets. Default `'div'`. */
10
+ as?: 'div' | 'section' | 'ul' | 'ol' | 'li';
11
+ /** Space between children, from the theme's `space` tokens, or `'none'`. Default `'md'`. */
12
+ gap?: Gap;
13
+ /** Cross-axis (horizontal) alignment of children. Default `'stretch'`. */
14
+ align?: 'stretch' | 'start' | 'center' | 'end';
15
+ /** Extra class on the root. Override with `'&&'` specificity, never `!important`. */
16
+ className?: string;
17
+ /** The children, laid out top to bottom. */
18
+ children?: ReactNode;
19
+ /** Ref to the root element. */
20
+ ref?: Ref<HTMLElement>;
21
+ }
22
+
23
+ /** Lays children out in a vertical column with a themed gap between them. */
24
+ export const Stack = ({
25
+ as = 'div',
26
+ gap = 'md',
27
+ align = 'stretch',
28
+ className,
29
+ children,
30
+ ref,
31
+ ...rest
32
+ }: StackProps) => {
33
+ const style = useStyle();
34
+ return createElement(
35
+ as,
36
+ {
37
+ ...rest,
38
+ ref,
39
+ className: cx(
40
+ style.root,
41
+ style[`gap-${gap}`],
42
+ style[`align-${align}`],
43
+ (as === 'ul' || as === 'ol') && style.list,
44
+ className
45
+ ),
46
+ },
47
+ children
48
+ );
49
+ };
@@ -0,0 +1,12 @@
1
+ import { createUseStyles, type Theme } from '../../theme/index.js';
2
+ import { gapRules } from './gap.js';
3
+
4
+ export const useStyle = createUseStyles((theme: Theme) => ({
5
+ root: { display: 'flex', flexDirection: 'column', minWidth: 0 },
6
+ list: { margin: 0, padding: 0, listStyle: 'none' },
7
+ 'align-stretch': { alignItems: 'stretch' },
8
+ 'align-start': { alignItems: 'flex-start' },
9
+ 'align-center': { alignItems: 'center' },
10
+ 'align-end': { alignItems: 'flex-end' },
11
+ ...gapRules(theme),
12
+ }));
@@ -11,7 +11,7 @@ export interface TagProps {
11
11
  onClick?: () => void;
12
12
  /** `sm` renders a compact chip that fits within a normal text line height. Default `'md'`. */
13
13
  size?: 'sm' | 'md';
14
- /** Colour, from the theme's `color.chip` tokens (default `'subject'`). `neutral` is a quiet grey. */
14
+ /** Colour, from the theme's `color.chip` tokens. Status tones (`success`, `warning`, `danger`, `info`, `neutral`) report state; label tones (the rest) name a kind of thing. `status` is a legacy label tone despite its name; for a state use `success`/`warning`/`danger`/`info`, or `neutral` when it carries no meaning. Default `subject`. */
15
15
  tone?: TagTone;
16
16
  }
17
17
 
@@ -0,0 +1,61 @@
1
+ import cx from 'classnames';
2
+ import type { HTMLAttributes, ReactNode, Ref } from 'react';
3
+ import { createElement } from 'react';
4
+
5
+ import { useStyle, useTypography, type TextSize, type TextTone, type TextWeight } from './style.js';
6
+
7
+ const INLINE_TAGS = ['span', 'strong', 'em', 'label'];
8
+
9
+ export interface TextProps extends Omit<HTMLAttributes<HTMLElement>, 'style'> {
10
+ /** The element to render. Default `'span'`. */
11
+ as?: 'span' | 'p' | 'div' | 'label' | 'strong' | 'em';
12
+ /** Font size, from the theme's `fontSize` tokens. Unset inherits. */
13
+ size?: TextSize;
14
+ /** Text colour: `primary`, `secondary`, `muted`, `faint`, `description`, or `danger`/`success` for inline error and confirmation text. Unset inherits. */
15
+ tone?: TextTone;
16
+ /** Font weight, from the theme's `fontWeight` tokens. Unset inherits. */
17
+ weight?: TextWeight;
18
+ /** Clip to one line with an ellipsis. Inline elements become `inline-block` so the clip applies. Default `false`. */
19
+ truncate?: boolean;
20
+ /** The id of the control this label describes. Only for `as="label"`. */
21
+ htmlFor?: string;
22
+ /** Extra class on the root. Override with `'&&'` specificity, never `!important`. */
23
+ className?: string;
24
+ /** The text. */
25
+ children?: ReactNode;
26
+ /** Ref to the root element. */
27
+ ref?: Ref<HTMLElement>;
28
+ }
29
+
30
+ /** A run of text with themed size, tone and weight. Unset props inherit from the parent. */
31
+ export const Text = ({
32
+ as = 'span',
33
+ size,
34
+ tone,
35
+ weight,
36
+ truncate = false,
37
+ className,
38
+ children,
39
+ ref,
40
+ ...rest
41
+ }: TextProps) => {
42
+ const style = useStyle();
43
+ const type = useTypography();
44
+ return createElement(
45
+ as,
46
+ {
47
+ ...rest,
48
+ ref,
49
+ className: cx(
50
+ style.root,
51
+ size && type[`size-${size}`],
52
+ tone && type[`tone-${tone}`],
53
+ weight && type[`weight-${weight}`],
54
+ truncate && type.truncate,
55
+ truncate && INLINE_TAGS.includes(as) && type.truncateInline,
56
+ className
57
+ ),
58
+ },
59
+ children
60
+ );
61
+ };
@@ -0,0 +1,67 @@
1
+ import { createUseStyles, type Theme } from '../../theme/index.js';
2
+
3
+ export type TextSize = keyof Theme['fontSize'];
4
+ export type TextTone =
5
+ | 'primary'
6
+ | 'secondary'
7
+ | 'muted'
8
+ | 'faint'
9
+ | 'description'
10
+ | 'danger'
11
+ | 'success';
12
+ export type TextWeight = keyof Theme['fontWeight'];
13
+
14
+ const toneColor = (theme: Theme, tone: TextTone): string => {
15
+ if (tone === 'danger') return theme.color.chip.danger.text;
16
+ if (tone === 'success') return theme.color.chip.success.text;
17
+ return theme.color.text[tone];
18
+ };
19
+
20
+ const TONES: TextTone[] = [
21
+ 'primary',
22
+ 'secondary',
23
+ 'muted',
24
+ 'faint',
25
+ 'description',
26
+ 'danger',
27
+ 'success',
28
+ ];
29
+
30
+ // One static rule per token value, so a prop is a class swap rather than a
31
+ // dynamic style sheet. Shared with Heading.
32
+ const typographyRules = (theme: Theme) => ({
33
+ ...(Object.fromEntries(
34
+ (Object.keys(theme.fontSize) as TextSize[]).map((size) => [
35
+ `size-${size}`,
36
+ { fontSize: theme.fontSize[size] },
37
+ ])
38
+ ) as Record<`size-${TextSize}`, object>),
39
+ ...(Object.fromEntries(
40
+ TONES.map((tone) => [`tone-${tone}`, { color: toneColor(theme, tone) }])
41
+ ) as Record<`tone-${TextTone}`, object>),
42
+ ...(Object.fromEntries(
43
+ (Object.keys(theme.fontWeight) as TextWeight[]).map((weight) => [
44
+ `weight-${weight}`,
45
+ { fontWeight: theme.fontWeight[weight] },
46
+ ])
47
+ ) as Record<`weight-${TextWeight}`, object>),
48
+ truncate: {
49
+ overflow: 'hidden',
50
+ textOverflow: 'ellipsis',
51
+ whiteSpace: 'nowrap',
52
+ minWidth: 0,
53
+ // A start, centre or end aligned flex item sizes to its content, so cap it.
54
+ maxWidth: '100%',
55
+ },
56
+ // Inline elements ignore overflow and width, so they become inline-block.
57
+ truncateInline: {
58
+ display: 'inline-block',
59
+ verticalAlign: 'bottom',
60
+ },
61
+ });
62
+
63
+ export const useTypography = createUseStyles((theme: Theme) => typographyRules(theme));
64
+
65
+ export const useStyle = createUseStyles(() => ({
66
+ root: { margin: 0 },
67
+ }));
@@ -27,7 +27,12 @@ export {
27
27
  type FooterAction,
28
28
  type PageFooterActionsProps,
29
29
  } from './page-footer-actions/index.js';
30
- export { Popover, type PopoverProps } from './popover/index.js';
30
+ export {
31
+ Popover,
32
+ type PopoverAlign,
33
+ type PopoverProps,
34
+ type PopoverSide,
35
+ } from './popover/index.js';
31
36
  export { Select, type SelectOption, type SelectProps } from './select/index.js';
32
37
  export {
33
38
  SegmentedControl,
@@ -10,12 +10,18 @@ import {
10
10
  } from 'react';
11
11
  import { createPortal } from 'react-dom';
12
12
 
13
+ import {
14
+ computePosition,
15
+ type Placement,
16
+ type PopoverAlign,
17
+ type PopoverSide,
18
+ } from './position.js';
13
19
  import { useStyle } from './style.js';
14
20
 
15
- type Position = { top: number; left: number; width: number };
21
+ export type { PopoverAlign, PopoverSide } from './position.js';
16
22
 
17
23
  export type PopoverProps = {
18
- /** Element the popover aligns to (positioned directly beneath it). */
24
+ /** Element the popover aligns to (placed below or above it, per `side`). */
19
25
  anchorRef: RefObject<HTMLElement | null>;
20
26
  /** Whether the popover is rendered. */
21
27
  open: boolean;
@@ -23,24 +29,38 @@ export type PopoverProps = {
23
29
  children: ReactNode;
24
30
  /** Applied to the fixed wrapper; win specificity with `'&&'`, never `!important`. */
25
31
  className?: string;
26
- /** Vertical gap between the anchor and the popover, in pixels. */
32
+ /** Vertical gap between the anchor and the popover, in pixels; also the viewport edge margin when `matchWidth` is false. */
27
33
  gap?: number;
28
34
  /** Match the popover width to the anchor width (default true). */
29
35
  matchWidth?: boolean;
36
+ /** Preferred side; flips to the other side when this one has no room. */
37
+ side?: PopoverSide;
38
+ /** Horizontal alignment to the anchor's left edge, centre, or right edge. */
39
+ align?: PopoverAlign;
30
40
  /**
31
- * Called on a pointer-down outside both the anchor and the popover content.
32
- * Omit to opt out of outside-close handling.
41
+ * Called on a pointer-down outside both the anchor and the popover content,
42
+ * and on an Escape keydown no control has already handled. Omit to opt out.
33
43
  */
34
44
  onClose?: () => void;
35
45
  };
36
46
 
37
47
  /**
38
48
  * Renders `children` in a portal on `document.body`, positioned with `fixed`
39
- * coordinates directly under `anchorRef`. This lets dropdowns escape ancestors
40
- * that clip overflow (e.g. cards with rounded corners) without those ancestors
49
+ * coordinates against `anchorRef`. This lets dropdowns escape ancestors that
50
+ * clip overflow (e.g. cards with rounded corners) without those ancestors
41
51
  * having to opt out of clipping.
42
52
  *
43
- * No Escape handling or focus management, and it never flips above the anchor.
53
+ * Opens on `side` (default below) and flips when that side has no room; aligns
54
+ * per `align` and clamps horizontally to the viewport (only without
55
+ * `matchWidth`). The wrapper carries `data-side` with the side actually used.
56
+ * On the top side it is anchored by CSS `bottom`, so it stays attached as its
57
+ * content changes height. The first render is transparent (`opacity: 0`, still
58
+ * focusable) until measured, then it re-measures on scroll (capture phase),
59
+ * window resize, and content resize (`ResizeObserver`, where available).
60
+ *
61
+ * With `onClose`, Escape closes it unless the keydown was already
62
+ * `defaultPrevented`; it calls `preventDefault` so an enclosing `<dialog>`
63
+ * does not also cancel. No focus management.
44
64
  */
45
65
  export const Popover = ({
46
66
  anchorRef,
@@ -49,18 +69,34 @@ export const Popover = ({
49
69
  className,
50
70
  gap = 4,
51
71
  matchWidth = true,
72
+ side = 'bottom',
73
+ align = 'start',
52
74
  onClose,
53
75
  }: PopoverProps) => {
54
76
  const style = useStyle();
55
77
  const contentRef = useRef<HTMLDivElement>(null);
56
- const [position, setPosition] = useState<Position | null>(null);
78
+ const [placement, setPlacement] = useState<Placement | null>(null);
57
79
 
58
80
  const updatePosition = useCallback(() => {
59
81
  const anchor = anchorRef.current;
60
- if (!anchor) return;
82
+ const content = contentRef.current;
83
+ if (!anchor || !content) return;
61
84
  const rect = anchor.getBoundingClientRect();
62
- setPosition({ top: rect.bottom + gap, left: rect.left, width: rect.width });
63
- }, [anchorRef, gap]);
85
+ // Measure at the width it will render with, so wrapped height is right.
86
+ if (matchWidth) content.style.width = `${rect.width}px`;
87
+ const size = content.getBoundingClientRect();
88
+ setPlacement(
89
+ computePosition({
90
+ anchor: rect,
91
+ content: { width: size.width, height: size.height },
92
+ viewport: { width: window.innerWidth, height: window.innerHeight },
93
+ side,
94
+ align,
95
+ gap,
96
+ matchWidth,
97
+ })
98
+ );
99
+ }, [anchorRef, gap, matchWidth, side, align]);
64
100
 
65
101
  useLayoutEffect(() => {
66
102
  if (!open) return;
@@ -69,9 +105,13 @@ export const Popover = ({
69
105
  // Capture-phase scroll so nested scroll containers reposition too.
70
106
  window.addEventListener('scroll', handle, true);
71
107
  window.addEventListener('resize', handle);
108
+ const observer = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(handle) : undefined;
109
+ if (observer && contentRef.current) observer.observe(contentRef.current);
72
110
  return () => {
73
111
  window.removeEventListener('scroll', handle, true);
74
112
  window.removeEventListener('resize', handle);
113
+ observer?.disconnect();
114
+ setPlacement(null);
75
115
  };
76
116
  }, [open, updatePosition]);
77
117
 
@@ -83,21 +123,39 @@ export const Popover = ({
83
123
  if (contentRef.current?.contains(target)) return;
84
124
  onClose();
85
125
  };
126
+ const handleKeyDown = (event: KeyboardEvent) => {
127
+ if (event.key !== 'Escape' || event.defaultPrevented) return;
128
+ // preventDefault on keydown is what stops a native <dialog> from cancelling.
129
+ event.preventDefault();
130
+ onClose();
131
+ };
86
132
  document.addEventListener('mousedown', handleMouseDown);
87
- return () => document.removeEventListener('mousedown', handleMouseDown);
133
+ document.addEventListener('keydown', handleKeyDown);
134
+ return () => {
135
+ document.removeEventListener('mousedown', handleMouseDown);
136
+ document.removeEventListener('keydown', handleKeyDown);
137
+ };
88
138
  }, [open, onClose, anchorRef]);
89
139
 
90
- if (!open || !position) return null;
140
+ if (!open) return null;
91
141
 
92
142
  return createPortal(
93
143
  <div
94
144
  ref={contentRef}
95
145
  className={cx(style.popover, className)}
96
- style={{
97
- top: position.top,
98
- left: position.left,
99
- width: matchWidth ? position.width : undefined,
100
- }}
146
+ data-side={placement?.side}
147
+ style={
148
+ placement
149
+ ? {
150
+ top: placement.top,
151
+ bottom: placement.bottom,
152
+ left: placement.left,
153
+ width: placement.width,
154
+ }
155
+ : // Never painted: the layout effect measures and re-renders first.
156
+ // Opacity, not visibility, so an autoFocus child can take focus.
157
+ { top: 0, left: 0, opacity: 0 }
158
+ }
101
159
  >
102
160
  {children}
103
161
  </div>,