From ac2db9f6b8234dd068ae4c26f6ae37921d12d94b Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 14:13:17 -0500 Subject: [PATCH 1/9] feat!: replace left/right prop values with start/end Directional props now use logical `start` / `end` values instead of physical `left` / `right`. - Disclosure `buttonPlacement` - Drawer `alignContentContainer` - Flyout `openFrom` - SelectDropdown `menuAlignment` - DataList column, ListCol, and FilterControl `justify` - Toggle `labelSide` - `iconPosition` on FillButton, StrokeButton, TextButton, Anchor, Tag, and Badge - GridForm section `layout` and `submit.position` Stories, docs, and agent skills are updated to match. Code Connect files keep `left` / `right` with TODO comments until the Figma changes take effect. BREAKING CHANGE: `left` and `right` are no longer accepted for these props. Use `start` in place of `left` and `end` in place of `right`. Co-Authored-By: Claude Opus 5.5 --- packages/code-connect/Atoms/Anchor.figma.tsx | 1 + packages/code-connect/Atoms/Drawer.figma.tsx | 1 + packages/code-connect/Molecules/Disclosure.figma.tsx | 1 + packages/code-connect/Molecules/Flyout.figma.tsx | 1 + packages/code-connect/Organisms/GridForm.figma.tsx | 3 +++ .../gamut-agent-tools/skills/gamut-buttons/SKILL.md | 2 +- .../gamut-agent-tools/skills/gamut-datatable/SKILL.md | 6 +++--- .../skills/gamut-select-dropdown/SKILL.md | 4 ++-- .../content/docs/components/containers/disclosure.mdx | 2 +- .../src/content/docs/components/containers/drawer.mdx | 2 +- .../data-display/list-and-tables/List/list-col.mdx | 4 ++-- .../components/inputs-and-forms/select-dropdown.mdx | 2 +- .../src/content/docs/components/navigation/anchor.mdx | 2 +- packages/gamut/src/Anchor/Anchor.stories.tsx | 6 +++--- packages/gamut/src/Anchor/index.tsx | 2 +- packages/gamut/src/Badge/index.tsx | 2 +- packages/gamut/src/Button/ButtonExamples.stories.tsx | 2 +- packages/gamut/src/Button/shared/InlineIconButton.tsx | 2 +- packages/gamut/src/Button/shared/types.ts | 2 +- packages/gamut/src/DataList/Controls/FilterControl.tsx | 6 +++--- packages/gamut/src/DataList/DataTable.stories.tsx | 2 +- packages/gamut/src/DataList/Tables/Rows/TableRow.tsx | 2 +- packages/gamut/src/DataList/testUtils.tsx | 6 +++--- packages/gamut/src/DataList/types.ts | 2 +- packages/gamut/src/Disclosure/DisclosureBody.tsx | 2 +- packages/gamut/src/Disclosure/elements.tsx | 8 ++++---- packages/gamut/src/Disclosure/helpers.tsx | 2 +- packages/gamut/src/Disclosure/types.ts | 4 ++-- packages/gamut/src/Drawer/Drawer.stories.tsx | 2 +- packages/gamut/src/Drawer/index.tsx | 6 +++--- packages/gamut/src/Flyout/index.tsx | 10 +++++----- packages/gamut/src/FocusTrap/FocusTrap.stories.tsx | 2 +- .../inputs/SelectDropdown/SelectDropdown.stories.tsx | 2 +- .../src/Form/inputs/SelectDropdown/SelectDropdown.tsx | 2 +- .../src/Form/inputs/SelectDropdown/core/styles.ts | 6 +++--- .../src/Form/inputs/SelectDropdown/types/styles.ts | 2 +- packages/gamut/src/GridForm/Buttons.stories.tsx | 10 +++++----- packages/gamut/src/GridForm/Fields.stories.tsx | 2 +- packages/gamut/src/GridForm/GridFormButtons/index.tsx | 6 +++--- packages/gamut/src/GridForm/Layout.stories.tsx | 4 ++-- packages/gamut/src/GridForm/States.stories.tsx | 2 +- packages/gamut/src/GridForm/Usage.stories.tsx | 8 ++++---- packages/gamut/src/GridForm/types.ts | 2 +- packages/gamut/src/List/List.stories.tsx | 4 ++-- packages/gamut/src/List/ListCol.stories.tsx | 2 +- packages/gamut/src/List/ListRow.stories.tsx | 2 +- packages/gamut/src/List/elements.tsx | 6 +++--- packages/gamut/src/Tag/index.tsx | 2 +- packages/gamut/src/Toggle/Toggle.stories.tsx | 4 ++-- packages/gamut/src/Toggle/elements.tsx | 2 +- packages/gamut/src/Toggle/index.tsx | 8 ++++---- packages/gamut/src/Toggle/types.tsx | 2 +- packages/gamut/src/helpers/appendIconToContent.tsx | 10 +++++----- .../.storybook/components/Elements/ComponentSource.tsx | 2 +- 54 files changed, 99 insertions(+), 92 deletions(-) diff --git a/packages/code-connect/Atoms/Anchor.figma.tsx b/packages/code-connect/Atoms/Anchor.figma.tsx index 1358383563..b68454d58d 100644 --- a/packages/code-connect/Atoms/Anchor.figma.tsx +++ b/packages/code-connect/Atoms/Anchor.figma.tsx @@ -23,6 +23,7 @@ figma.connect( false: undefined, }), }), + // TODO: Update these 'left' / 'right' values to 'start' / 'end' after the Figma changes take effect. iconPosition: figma.boolean('👁 leading icon', { true: 'left', false: figma.boolean('👁 trailing icon', { diff --git a/packages/code-connect/Atoms/Drawer.figma.tsx b/packages/code-connect/Atoms/Drawer.figma.tsx index 302c5af417..613ab4fd49 100644 --- a/packages/code-connect/Atoms/Drawer.figma.tsx +++ b/packages/code-connect/Atoms/Drawer.figma.tsx @@ -14,6 +14,7 @@ figma.connect( 'https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=115820-91241', { props: { + // TODO: Update these 'left' / 'right' values to 'start' / 'end' after the Figma changes take effect. alignContentContainer: figma.enum('alignContentContainer', { left: 'left', right: 'right', diff --git a/packages/code-connect/Molecules/Disclosure.figma.tsx b/packages/code-connect/Molecules/Disclosure.figma.tsx index 75cf2e2675..6355a33c0f 100644 --- a/packages/code-connect/Molecules/Disclosure.figma.tsx +++ b/packages/code-connect/Molecules/Disclosure.figma.tsx @@ -46,6 +46,7 @@ figma.connect( }), }), buttonInfo: figma.nestedProps('.cta', { + // TODO: Update these 'left' / 'right' values to 'start' / 'end' after the Figma changes take effect. buttonPlacement: figma.enum('buttonPlacement', { left: 'left', right: 'right', diff --git a/packages/code-connect/Molecules/Flyout.figma.tsx b/packages/code-connect/Molecules/Flyout.figma.tsx index 51d9572a74..2607cd4dab 100644 --- a/packages/code-connect/Molecules/Flyout.figma.tsx +++ b/packages/code-connect/Molecules/Flyout.figma.tsx @@ -14,6 +14,7 @@ figma.connect( 'https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=6329%3A5647', { props: { + // TODO: Update these 'left' / 'right' values to 'start' / 'end' after the Figma changes take effect. openFrom: figma.enum('openFrom', { left: 'left', right: 'right', diff --git a/packages/code-connect/Organisms/GridForm.figma.tsx b/packages/code-connect/Organisms/GridForm.figma.tsx index b70111e0a5..8202d04dd5 100644 --- a/packages/code-connect/Organisms/GridForm.figma.tsx +++ b/packages/code-connect/Organisms/GridForm.figma.tsx @@ -64,6 +64,7 @@ figma.connect( Sections: [ { title: 'Section Header', + // TODO: Update this 'left' value to 'start' after the Figma changes take effect. layout: 'left', variant: 'title-md', fields: [ @@ -85,6 +86,7 @@ figma.connect( }, { title: 'Section Header', + // TODO: Update this 'left' value to 'start' after the Figma changes take effect. layout: 'left', variant: 'title-md', fields: [ @@ -108,6 +110,7 @@ figma.connect( }, ], }), + // TODO: Update these 'left' / 'right' position values to 'start' / 'end' after the Figma changes take effect. submit: figma.enum('Template', { Starter: { contents: 'Submit form', diff --git a/packages/gamut-agent-tools/skills/gamut-buttons/SKILL.md b/packages/gamut-agent-tools/skills/gamut-buttons/SKILL.md index 073ad5e816..47491ce4d0 100644 --- a/packages/gamut-agent-tools/skills/gamut-buttons/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-buttons/SKILL.md @@ -55,7 +55,7 @@ Shared by `FillButton`, `StrokeButton`, `TextButton`, and `IconButton`. `CTAButt | `variant` | `"primary" \| "secondary" \| "danger" \| "interface"` | Color emphasis (see table above) | | `size` | `"small" \| "normal" \| "large"` | Padding and font size | | `icon` | Icon component | Leading or trailing icon (Fill, Stroke, Text) | -| `iconPosition` | `"left" \| "right"` | Defaults to left | +| `iconPosition` | `"start" \| "end"` | Defaults to start | | `disabled` | boolean | Disabled state styling | | `href` | string | Renders as `` tag | | `tip` | string | Required on `IconButton` (tooltip + hover label) | diff --git a/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md b/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md index b54af6868d..3cd4e121cf 100644 --- a/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md @@ -76,7 +76,7 @@ import { useLocalQuery } from '@skillsoft/gamut'; | `type` | `'content' \| 'header' \| 'control' \| 'select' \| 'expand' \| 'expandControl' \| 'orderedHeader' \| 'tableControl'` | `ListColProps['type']`; `'content'` is default — see [Column `type`](#column-type) | | `size` | `'content' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'content'` (default) fits cell contents; use `sm`–`xl` for fixed column widths | | `fill` | `boolean` | Expands the column to fill remaining width | -| `justify` | `'left' \| 'right'` | Cell alignment | +| `justify` | `'start' \| 'end'` | Cell alignment | | `sortable` | `boolean` | Adds a sort toggle to the column header | | `filters` | `string[]` | Adds a filter dropdown with these string values | | `options` | `Array` | Alternative to `filters` when display text differs from value | @@ -115,7 +115,7 @@ const columns = [ header: 'Score', size: 'sm', sortable: true, - justify: 'right', + justify: 'end', }, ]; @@ -217,7 +217,7 @@ const columns = [ header: '', size: 'sm', type: 'control', - justify: 'right', + justify: 'end', render: (row) => , }, ]; diff --git a/packages/gamut-agent-tools/skills/gamut-select-dropdown/SKILL.md b/packages/gamut-agent-tools/skills/gamut-select-dropdown/SKILL.md index 42e1a48de1..f8b9623f02 100644 --- a/packages/gamut-agent-tools/skills/gamut-select-dropdown/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-select-dropdown/SKILL.md @@ -34,7 +34,7 @@ The table below shows the keys and value types for an option object: | `disabled` | `boolean` | no | Option cannot be selected | | `subtitle` | `string` | no | Secondary text below the label | | `rightLabel` | `string` | no | Text on the right side of the option | -| `icon` | icon component from `gamut-icons` | no | A `@skillsoft/gamut-icons` component | +| `icon` | icon component from `gamut-icons` | no | A `@skillsoft/gamut-icons` component | | `abbreviation` | `string` | no | Short text shown in the input while the full label shows in the menu | Grouped options: `{ label, options: [...], divider? }` (extends react-select `GroupBase`; `divider` draws a rule above the group). @@ -172,7 +172,7 @@ const lastInput = useRef(''); | `shownOptionsLimit` | `1`–`6` | `6` | Visible options before the menu scrolls | | `inputWidth` | `string \| number` | — | Width of the input independent of the menu | | `dropdownWidth` | `string \| number` | — | Width of the menu independent of the input | -| `menuAlignment` | `'left' \| 'right'` | `left` | Menu edge alignment | +| `menuAlignment` | `'start' \| 'end'` | `start` | Menu edge alignment | | `zIndex` | `number` | `2` | Menu z-index (control container defaults to `3`) | | `inputProps` | `{ hidden?, combobox? }` | — | `data-*` / `aria-*` only, forwarded to the input elements | diff --git a/packages/gamut-docs/src/content/docs/components/containers/disclosure.mdx b/packages/gamut-docs/src/content/docs/components/containers/disclosure.mdx index 7d99f67a97..4749e7d578 100644 --- a/packages/gamut-docs/src/content/docs/components/containers/disclosure.mdx +++ b/packages/gamut-docs/src/content/docs/components/containers/disclosure.mdx @@ -36,7 +36,7 @@ Use a `Disclosure` to progressively reveal information, letting a reader access ### Adding a call-to-action button -Pass `ctaText` and `ctaCallback` together to render a button at the bottom of the body — both are required for it to appear. `buttonType` (`'FillButton' | 'StrokeButton' | 'TextButton'`, default `'TextButton'`) picks which button component renders it, and `buttonPlacement` (`'left' | 'right'`, default `'right'`) picks its alignment: +Pass `ctaText` and `ctaCallback` together to render a button at the bottom of the body — both are required for it to appear. `buttonType` (`'FillButton' | 'StrokeButton' | 'TextButton'`, default `'TextButton'`) picks which button component renders it, and `buttonPlacement` (`'start' | 'end'`, default `'end'`) picks its alignment: ```tsx diff --git a/packages/gamut-docs/src/content/docs/components/data-display/list-and-tables/List/list-col.mdx b/packages/gamut-docs/src/content/docs/components/data-display/list-and-tables/List/list-col.mdx index 6c7f9d2861..9f423cf702 100644 --- a/packages/gamut-docs/src/content/docs/components/data-display/list-and-tables/List/list-col.mdx +++ b/packages/gamut-docs/src/content/docs/components/data-display/list-and-tables/List/list-col.mdx @@ -42,9 +42,9 @@ Pass `fill` on one or more columns in a row to have them grow and consume whatev height="8rem" /> -### Right-aligning content +### End-aligning content -Pass `justify="right"`. Avoid mixing left- and right-justified columns within the same list — it makes scanning harder: +Pass `justify="end"`. Avoid mixing start- and end-justified columns within the same list — it makes scanning harder: diff --git a/packages/gamut/src/Anchor/Anchor.stories.tsx b/packages/gamut/src/Anchor/Anchor.stories.tsx index 020eac3ca1..2a7d8541d3 100644 --- a/packages/gamut/src/Anchor/Anchor.stories.tsx +++ b/packages/gamut/src/Anchor/Anchor.stories.tsx @@ -24,7 +24,7 @@ const meta: Meta = { children: 'Click me', href: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', icon: icons.MiniInfoOutlineIcon, - iconPosition: 'left', + iconPosition: 'start', target: '_blank', variant: 'inline', }, @@ -95,7 +95,7 @@ export const IconAnchor: Story = { {...args} href="/" icon={icons.MiniInfoOutlineIcon} - iconPosition="left" + iconPosition="start" variant="inline" > Anybody can do what I do. @@ -106,7 +106,7 @@ export const IconAnchor: Story = { {...args} href="/" icon={icons.MiniArrowRightIcon} - iconPosition="right" + iconPosition="end" variant="inline" > Learn more diff --git a/packages/gamut/src/Anchor/index.tsx b/packages/gamut/src/Anchor/index.tsx index 34af1ecbb7..dede138fe9 100644 --- a/packages/gamut/src/Anchor/index.tsx +++ b/packages/gamut/src/Anchor/index.tsx @@ -142,7 +142,7 @@ export const Anchor = forwardRef< children, icon, iconOffset, - iconPosition = 'left', + iconPosition = 'start', iconSize = 16, iconAndTextGap = 8, isInlineIcon = true, diff --git a/packages/gamut/src/Badge/index.tsx b/packages/gamut/src/Badge/index.tsx index 5a0da3b84a..17d86571dc 100644 --- a/packages/gamut/src/Badge/index.tsx +++ b/packages/gamut/src/Badge/index.tsx @@ -122,7 +122,7 @@ export const Badge: React.FC = ({ icon, children, ...rest }) => { children, icon, iconAndTextGap: spacing, - iconPosition: 'left', + iconPosition: 'start', iconSize, }); return {content}; diff --git a/packages/gamut/src/Button/ButtonExamples.stories.tsx b/packages/gamut/src/Button/ButtonExamples.stories.tsx index 8822aa8c56..c575bc66e7 100644 --- a/packages/gamut/src/Button/ButtonExamples.stories.tsx +++ b/packages/gamut/src/Button/ButtonExamples.stories.tsx @@ -34,7 +34,7 @@ export const InlineIcons: Story = { TextButton diff --git a/packages/gamut/src/Button/shared/InlineIconButton.tsx b/packages/gamut/src/Button/shared/InlineIconButton.tsx index cf3ae6d82c..c608d352bf 100644 --- a/packages/gamut/src/Button/shared/InlineIconButton.tsx +++ b/packages/gamut/src/Button/shared/InlineIconButton.tsx @@ -25,7 +25,7 @@ export const InlineIconButton = forwardRef< children, button: Button, icon, - iconPosition = 'left', + iconPosition = 'start', variant, ...props }, diff --git a/packages/gamut/src/Button/shared/types.ts b/packages/gamut/src/Button/shared/types.ts index 57478c935b..a4690e7887 100644 --- a/packages/gamut/src/Button/shared/types.ts +++ b/packages/gamut/src/Button/shared/types.ts @@ -29,7 +29,7 @@ export type InlineIconButtonProps< | React.JSXElementConstructor > = ComponentProps & Partial & { - iconPosition?: 'right' | 'left'; + iconPosition?: 'start' | 'end'; }; /* eslint-disable @typescript-eslint/no-duplicate-type-constituents -- createButtonComponent yields structurally identical typeofs; union documents distinct components */ diff --git a/packages/gamut/src/DataList/Controls/FilterControl.tsx b/packages/gamut/src/DataList/Controls/FilterControl.tsx index a6811066e4..848b0acd88 100644 --- a/packages/gamut/src/DataList/Controls/FilterControl.tsx +++ b/packages/gamut/src/DataList/Controls/FilterControl.tsx @@ -16,7 +16,7 @@ export interface FilterProps { columnKey: string; options?: FilterOption[]; onFilter?: OnFilter; - justify?: 'left' | 'right'; + justify?: 'start' | 'end'; } const getNextFilters = (option: string, filters: string[]) => { @@ -51,7 +51,7 @@ export const FilterControl: React.FC = ({ columnKey, onFilter, options = [], - justify = 'left', + justify = 'start', }) => { const target = useRef(null); const { prefixId } = useControlContext(); @@ -63,7 +63,7 @@ export const FilterControl: React.FC = ({ {menuOpen && ( , }, diff --git a/packages/gamut/src/DataList/Tables/Rows/TableRow.tsx b/packages/gamut/src/DataList/Tables/Rows/TableRow.tsx index 4d872d8642..fb4d3266c6 100644 --- a/packages/gamut/src/DataList/Tables/Rows/TableRow.tsx +++ b/packages/gamut/src/DataList/Tables/Rows/TableRow.tsx @@ -157,7 +157,7 @@ export const TableRow: DataRow = ({ render(row) ) : typeof row[key] === 'string' || typeof row[key] === 'number' ? ( diff --git a/packages/gamut/src/DataList/testUtils.tsx b/packages/gamut/src/DataList/testUtils.tsx index 6f0cb66595..a09d201b6f 100644 --- a/packages/gamut/src/DataList/testUtils.tsx +++ b/packages/gamut/src/DataList/testUtils.tsx @@ -274,7 +274,7 @@ export const cols: ColumnConfig[] = [ header: 'Species', key: 'species', size: 'lg', - justify: 'right', + justify: 'end', sortable: true, filters: ['Human'], }, @@ -282,7 +282,7 @@ export const cols: ColumnConfig[] = [ header: 'Controls', key: 'name', size: 'md', - justify: 'right', + justify: 'end', type: 'control', render: (row) => , }, @@ -375,7 +375,7 @@ export const simpleRows = [ export const simpleColumns: ColumnConfig<(typeof simpleRows)[number]>[] = [ { key: 'name', header: 'Name', type: 'header', size: 'md' }, - { key: 'role', header: 'Role', fill: true, justify: 'right' }, + { key: 'role', header: 'Role', fill: true, justify: 'end' }, { header: 'Controls', key: 'name', diff --git a/packages/gamut/src/DataList/types.ts b/packages/gamut/src/DataList/types.ts index 50e9375bf0..711a2ec7c5 100644 --- a/packages/gamut/src/DataList/types.ts +++ b/packages/gamut/src/DataList/types.ts @@ -82,7 +82,7 @@ export interface ColumnConfig { * Working with the `size` prop, will indicate that this field should expand to fill extra space. */ fill?: boolean; - justify?: 'left' | 'right'; + justify?: 'start' | 'end'; } interface RowChangePayload { diff --git a/packages/gamut/src/Disclosure/DisclosureBody.tsx b/packages/gamut/src/Disclosure/DisclosureBody.tsx index 803a9ca88a..fb9d8cf360 100644 --- a/packages/gamut/src/Disclosure/DisclosureBody.tsx +++ b/packages/gamut/src/Disclosure/DisclosureBody.tsx @@ -8,7 +8,7 @@ import type { DisclosureBodyProps } from './types'; export const DisclosureBody: React.FC = ({ body, buttonType = 'TextButton', - buttonPlacement = 'right', + buttonPlacement = 'end', ctaCallback, ctaText, hasPanelBg = false, diff --git a/packages/gamut/src/Disclosure/elements.tsx b/packages/gamut/src/Disclosure/elements.tsx index 4903d7a234..155382a1ec 100644 --- a/packages/gamut/src/Disclosure/elements.tsx +++ b/packages/gamut/src/Disclosure/elements.tsx @@ -72,13 +72,13 @@ export const DisclosureButtonWrapper = styled(Anchor)( ); const sharedVariants = { - left: { + start: { alignSelf: 'flex-start', - justifyContent: 'left', + justifyContent: 'start', }, - right: { + end: { alignSelf: 'flex-end', - justifyContent: 'right', + justifyContent: 'end', }, }; diff --git a/packages/gamut/src/Disclosure/helpers.tsx b/packages/gamut/src/Disclosure/helpers.tsx index 6d0c590d00..22a6c350b0 100644 --- a/packages/gamut/src/Disclosure/helpers.tsx +++ b/packages/gamut/src/Disclosure/helpers.tsx @@ -40,7 +40,7 @@ export const getRotationSize = ( }; export const renderButton = (buttonProps: { - buttonPlacement: 'left' | 'right'; + buttonPlacement: 'start' | 'end'; buttonType: 'FillButton' | 'StrokeButton' | 'TextButton'; ctaCallback: () => void; ctaText: string; diff --git a/packages/gamut/src/Disclosure/types.ts b/packages/gamut/src/Disclosure/types.ts index 68abaaa7ee..523c97fec0 100644 --- a/packages/gamut/src/Disclosure/types.ts +++ b/packages/gamut/src/Disclosure/types.ts @@ -40,9 +40,9 @@ export interface DisclosureBodyProps extends DisclosureBodyWrapperStyles { */ buttonType?: 'FillButton' | 'StrokeButton' | 'TextButton'; /** - * You can specify `"right"` (default) or `"left"` placement of the optional button at the bottom of the body. + * You can specify `"end"` (default) or `"start"` placement of the optional button at the bottom of the body. */ - buttonPlacement?: 'left' | 'right'; + buttonPlacement?: 'start' | 'end'; /** * A callback function MUST be included when providing a `ctaButton` to render the optional button. */ diff --git a/packages/gamut/src/Drawer/Drawer.stories.tsx b/packages/gamut/src/Drawer/Drawer.stories.tsx index 55ab1c7b2e..c0823679ab 100644 --- a/packages/gamut/src/Drawer/Drawer.stories.tsx +++ b/packages/gamut/src/Drawer/Drawer.stories.tsx @@ -11,7 +11,7 @@ const meta: Meta = { component: Drawer, args: { expanded: true, - alignContentContainer: 'left', + alignContentContainer: 'start', }, render: function DrawerDemo(args) { const [expanded, setExpanded] = useState(args.expanded); diff --git a/packages/gamut/src/Drawer/index.tsx b/packages/gamut/src/Drawer/index.tsx index 663fac6081..11febeed8f 100644 --- a/packages/gamut/src/Drawer/index.tsx +++ b/packages/gamut/src/Drawer/index.tsx @@ -19,11 +19,11 @@ export interface DrawerProps extends Omit { /** * Which edge of the drawer content container is aligned to during the animation. */ - alignContentContainer?: 'left' | 'right'; + alignContentContainer?: 'start' | 'end'; } export const Drawer: React.FC = ({ - alignContentContainer = 'right', + alignContentContainer = 'end', children, expanded, ...props @@ -54,7 +54,7 @@ export const Drawer: React.FC = ({ = ({ children, closeLabel = 'Close', expanded, - openFrom = 'left', + openFrom = 'start', onClose, title, }) => { @@ -57,14 +57,14 @@ export const Flyout: React.FC = ({ > = { ]} submit={{ contents: 'Disable Focus Trap', - position: 'right', + position: 'end', size: 12, }} onSubmit={() => { diff --git a/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.stories.tsx b/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.stories.tsx index c8ca2b3c5d..1c526f1d0c 100644 --- a/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.stories.tsx +++ b/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.stories.tsx @@ -1491,7 +1491,7 @@ export const MenuAlignmentRight: Story = { ], inputWidth: '150px', dropdownWidth: '300px', - menuAlignment: 'right', + menuAlignment: 'end', translations: { placeholder: 'Select a role' }, }, render: (args) => ( diff --git a/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.tsx b/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.tsx index 81d490af23..33ca256423 100644 --- a/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.tsx +++ b/packages/gamut/src/Form/inputs/SelectDropdown/SelectDropdown.tsx @@ -81,7 +81,7 @@ export const SelectDropdown: React.FC = ({ isCreatable = false, isSearchable: isSearchableProp = false, isValidNewOption, - menuAlignment = 'left', + menuAlignment = 'start', multiple, name, onChange, diff --git a/packages/gamut/src/Form/inputs/SelectDropdown/core/styles.ts b/packages/gamut/src/Form/inputs/SelectDropdown/core/styles.ts index cccb777405..fed839ea49 100644 --- a/packages/gamut/src/Form/inputs/SelectDropdown/core/styles.ts +++ b/packages/gamut/src/Form/inputs/SelectDropdown/core/styles.ts @@ -154,10 +154,10 @@ export const getMemoizedStyles = ( width: dropdownWidth, } : {}), - ...(menuAlignment === 'right' + ...(menuAlignment === 'end' ? { - left: 'auto', - right: 0, + insetInlineStart: 'auto', + insetInlineEnd: 0, } : {}), }; diff --git a/packages/gamut/src/Form/inputs/SelectDropdown/types/styles.ts b/packages/gamut/src/Form/inputs/SelectDropdown/types/styles.ts index d46fdeaea3..ccf7f22854 100644 --- a/packages/gamut/src/Form/inputs/SelectDropdown/types/styles.ts +++ b/packages/gamut/src/Form/inputs/SelectDropdown/types/styles.ts @@ -22,7 +22,7 @@ export interface SharedProps extends InternalInputsProps, SelectDropdownSizes { /** Alignment of the dropdown menu relative to the input * This is only relevant when the dropdown width is set to be larger or smaller than the input width. */ - menuAlignment?: 'left' | 'right'; + menuAlignment?: 'start' | 'end'; /** Z-index for the dropdown menu */ zIndex?: number; } diff --git a/packages/gamut/src/GridForm/Buttons.stories.tsx b/packages/gamut/src/GridForm/Buttons.stories.tsx index 423da55a5a..39527d34fc 100644 --- a/packages/gamut/src/GridForm/Buttons.stories.tsx +++ b/packages/gamut/src/GridForm/Buttons.stories.tsx @@ -32,7 +32,7 @@ export const SubmitButtonRight: Story = { args: { submit: { contents: 'Right Submit!?', - position: 'right', + position: 'end', size: 12, }, }, @@ -51,7 +51,7 @@ export const SubmitButtonLeft: Story = { args: { submit: { contents: 'Left Submit!?', - position: 'left', + position: 'start', size: 12, }, }, @@ -115,7 +115,7 @@ export const SubmitButtonInline: Story = { submit: { contents: 'Inline Submit!?', size: 4, - position: 'right', + position: 'end', }, }, }; @@ -128,7 +128,7 @@ export const CancelButton: Story = { }, submit: { contents: 'Submit!?', - position: 'right', + position: 'end', size: 12, }, }, @@ -185,7 +185,7 @@ export const CancelLink: Story = { }, submit: { contents: 'Save', - position: 'right', + position: 'end', size: 12, }, }, diff --git a/packages/gamut/src/GridForm/Fields.stories.tsx b/packages/gamut/src/GridForm/Fields.stories.tsx index 9f525d3ab6..0a934d4b15 100644 --- a/packages/gamut/src/GridForm/Fields.stories.tsx +++ b/packages/gamut/src/GridForm/Fields.stories.tsx @@ -16,7 +16,7 @@ const meta: Meta = { submit: { contents: 'Submit', size: 4, - position: 'left', + position: 'start', }, }, }; diff --git a/packages/gamut/src/GridForm/GridFormButtons/index.tsx b/packages/gamut/src/GridForm/GridFormButtons/index.tsx index 0eb89ddba5..4f8bf2b121 100644 --- a/packages/gamut/src/GridForm/GridFormButtons/index.tsx +++ b/packages/gamut/src/GridForm/GridFormButtons/index.tsx @@ -34,9 +34,9 @@ type CancelButtonProps = { }; const positions = { - left: 'flex-start', + start: 'flex-start', center: 'center', - right: 'flex-end', + end: 'flex-end', stretch: 'stretch', }; @@ -53,7 +53,7 @@ export const GridFormButtons: React.FC< {props.cancel && ( diff --git a/packages/gamut/src/GridForm/Layout.stories.tsx b/packages/gamut/src/GridForm/Layout.stories.tsx index b618507cde..1bef73018d 100644 --- a/packages/gamut/src/GridForm/Layout.stories.tsx +++ b/packages/gamut/src/GridForm/Layout.stories.tsx @@ -15,7 +15,7 @@ const meta: Meta = { submit: { contents: 'Submit', size: 4, - position: 'left', + position: 'start', }, }, }; @@ -220,7 +220,7 @@ export const Sections: Story = { fields: [ { title: 'first section', - layout: 'left', + layout: 'start', variant: 'title-xs', titleWrapperProps: { color: 'danger', diff --git a/packages/gamut/src/GridForm/States.stories.tsx b/packages/gamut/src/GridForm/States.stories.tsx index 8984ccad61..5ab7c4fbc4 100644 --- a/packages/gamut/src/GridForm/States.stories.tsx +++ b/packages/gamut/src/GridForm/States.stories.tsx @@ -23,7 +23,7 @@ const meta: Meta = { submit: { contents: 'Submit', size: 4, - position: 'left', + position: 'start', }, hideRequiredText: true, }, diff --git a/packages/gamut/src/GridForm/Usage.stories.tsx b/packages/gamut/src/GridForm/Usage.stories.tsx index 8be855464a..8eb9eb1c95 100644 --- a/packages/gamut/src/GridForm/Usage.stories.tsx +++ b/packages/gamut/src/GridForm/Usage.stories.tsx @@ -154,7 +154,7 @@ const meta: TypeWithDeepControls> = { submit: { contents: 'Submit Me!?', size: 4, - position: 'left', + position: 'start', disabled: false, loading: false, type: 'fill', @@ -176,10 +176,10 @@ const meta: TypeWithDeepControls> = { }, 'submit.position': { control: 'radio', - options: ['left', 'center', 'right', 'stretch'], + options: ['start', 'center', 'end', 'stretch'], table: { - defaultValue: { summary: 'left' }, - type: { summary: 'left | center | right | stretch' }, + defaultValue: { summary: 'start' }, + type: { summary: 'start | center | end | stretch' }, }, description: 'The position of the submit button.', }, diff --git a/packages/gamut/src/GridForm/types.ts b/packages/gamut/src/GridForm/types.ts index b6f8ca9275..a479f28b89 100644 --- a/packages/gamut/src/GridForm/types.ts +++ b/packages/gamut/src/GridForm/types.ts @@ -194,7 +194,7 @@ export type GridFormRequiredTextProps = { export type GridFormSectionTitleBaseProps = RestrictedTitleVariant & { title: string; as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'; - layout?: 'center' | 'left'; + layout?: 'center' | 'start'; titleWrapperProps?: BoxProps; }; diff --git a/packages/gamut/src/List/List.stories.tsx b/packages/gamut/src/List/List.stories.tsx index b8e949ded8..1e5af4cc95 100644 --- a/packages/gamut/src/List/List.stories.tsx +++ b/packages/gamut/src/List/List.stories.tsx @@ -753,7 +753,7 @@ export const DisableContainerQuery: Story = { {name} {ship} - + {ship} @@ -769,7 +769,7 @@ export const DisableContainerQuery: Story = { {name} {ship} - + {ship} diff --git a/packages/gamut/src/List/ListCol.stories.tsx b/packages/gamut/src/List/ListCol.stories.tsx index e454c787f6..a6a99782d9 100644 --- a/packages/gamut/src/List/ListCol.stories.tsx +++ b/packages/gamut/src/List/ListCol.stories.tsx @@ -186,7 +186,7 @@ export const Justification: ListCompositionStory = { Left - + Right diff --git a/packages/gamut/src/List/ListRow.stories.tsx b/packages/gamut/src/List/ListRow.stories.tsx index bb45024e8a..f2fd8d0565 100644 --- a/packages/gamut/src/List/ListRow.stories.tsx +++ b/packages/gamut/src/List/ListRow.stories.tsx @@ -248,7 +248,7 @@ export const PlainStyled: Story = { A dangerous styled item More styled content - + diff --git a/packages/gamut/src/List/elements.tsx b/packages/gamut/src/List/elements.tsx index 73ebbfdb6b..95f6d9fc60 100644 --- a/packages/gamut/src/List/elements.tsx +++ b/packages/gamut/src/List/elements.tsx @@ -298,16 +298,16 @@ const columnType = variant({ const columnJustify = variant({ prop: 'justify', - defaultVariant: 'left', + defaultVariant: 'start', variants: { - left: { + start: { justifyContent: { _: 'flex-start', c_base: 'initial', c_sm: 'flex-start', }, }, - right: { + end: { justifyContent: { _: 'flex-end', c_base: 'initial', c_sm: 'flex-end' }, '& div': { width: { sm: 'fit-content' }, diff --git a/packages/gamut/src/Tag/index.tsx b/packages/gamut/src/Tag/index.tsx index 220f17c6ac..e943921a35 100644 --- a/packages/gamut/src/Tag/index.tsx +++ b/packages/gamut/src/Tag/index.tsx @@ -34,7 +34,7 @@ export const Tag: React.FC = ({ children, icon, iconAndTextGap: 8, - iconPosition: 'left', + iconPosition: 'start', iconSize: 16, }); diff --git a/packages/gamut/src/Toggle/Toggle.stories.tsx b/packages/gamut/src/Toggle/Toggle.stories.tsx index 9c863d6edc..6c3565d4df 100644 --- a/packages/gamut/src/Toggle/Toggle.stories.tsx +++ b/packages/gamut/src/Toggle/Toggle.stories.tsx @@ -64,14 +64,14 @@ export const DisabledChecked: Story = { export const LabelLeft: Story = { args: { label: 'My label is to the left', - labelSide: 'left', + labelSide: 'start', }, }; export const LabelRight: Story = { args: { label: 'My label is to the right', - labelSide: 'right', + labelSide: 'end', }, }; diff --git a/packages/gamut/src/Toggle/elements.tsx b/packages/gamut/src/Toggle/elements.tsx index d53c132d26..910ee5e870 100644 --- a/packages/gamut/src/Toggle/elements.tsx +++ b/packages/gamut/src/Toggle/elements.tsx @@ -72,7 +72,7 @@ export const ToggleInput = styled.input(screenReaderOnly); const ToggleLabelStates = states({ disabled: { cursor: 'not-allowed', opacity: 0.5 }, - labelRight: { flexDirection: 'row-reverse' }, + labelEnd: { flexDirection: 'row-reverse' }, }); export type ToggleStyleProps = StyleProps; diff --git a/packages/gamut/src/Toggle/index.tsx b/packages/gamut/src/Toggle/index.tsx index ed82fee81e..a276d6f73f 100644 --- a/packages/gamut/src/Toggle/index.tsx +++ b/packages/gamut/src/Toggle/index.tsx @@ -8,7 +8,7 @@ export const Toggle = ({ checked, disabled, label, - labelSide = 'right', + labelSide = 'end', onChange, onClick, size = 'medium', @@ -30,14 +30,14 @@ export const Toggle = ({ {label && <>{label}} diff --git a/packages/gamut/src/Toggle/types.tsx b/packages/gamut/src/Toggle/types.tsx index 286f63c4bc..22b07d6f81 100644 --- a/packages/gamut/src/Toggle/types.tsx +++ b/packages/gamut/src/Toggle/types.tsx @@ -20,7 +20,7 @@ export interface ToggleBaseProps extends ToggleStyleProps { /** A visible label for your Toggle - we reccommend this */ label?: React.ReactNode; /** Which side of the toggle the label should render */ - labelSide?: 'left' | 'right'; + labelSide?: 'start' | 'end'; /** Changes the dimensions of the element for using the component outside of a form context */ size?: ToggleSizes; } diff --git a/packages/gamut/src/helpers/appendIconToContent.tsx b/packages/gamut/src/helpers/appendIconToContent.tsx index 8f4bb32e4f..2a13c6f30f 100644 --- a/packages/gamut/src/helpers/appendIconToContent.tsx +++ b/packages/gamut/src/helpers/appendIconToContent.tsx @@ -14,9 +14,9 @@ export interface AppendedIconProps */ iconOffset?: number; /** - * Can set the positioning of the icon relative to children, default is `left` + * Can set the positioning of the icon relative to children, default is `start` */ - iconPosition?: 'left' | 'right'; + iconPosition?: 'start' | 'end'; /** * This value determines the size of the icon */ @@ -38,8 +38,8 @@ export const appendIconToContent = ({ }: AppendedIconProps) => { if (!Icon) return <>{children}; - const iconSpacing = iconPosition === 'left' ? 'mr' : 'ml'; - const iconPositioning = iconPosition === 'left' ? 0 : 1; + const iconSpacing = iconPosition === 'start' ? 'mr' : 'ml'; + const iconPositioning = iconPosition === 'start' ? 0 : 1; if (typeof iconOffset !== 'number') { iconOffset = isInlineIcon ? 2 : 4; @@ -66,7 +66,7 @@ export const appendIconToContent = ({ ); const content = - iconPosition === 'left' ? ( + iconPosition === 'start' ? ( <> {InlineCenteredIcon} {children} diff --git a/packages/styleguide/.storybook/components/Elements/ComponentSource.tsx b/packages/styleguide/.storybook/components/Elements/ComponentSource.tsx index 3fe56da10f..01bd882640 100644 --- a/packages/styleguide/.storybook/components/Elements/ComponentSource.tsx +++ b/packages/styleguide/.storybook/components/Elements/ComponentSource.tsx @@ -9,7 +9,7 @@ export const SourceAnchor = styled(Anchor)( export const sourceAnchorProps = { icon: OpenIcon, - iconPosition: 'right', + iconPosition: 'end', target: '_blank', } as const; From b99dfb0daf1f8338d48d448d55dc52b0efbdc0d6 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 14:33:54 -0500 Subject: [PATCH 2/9] feat!: replace left/right alignment values with start/end in Popover, PopoverContainer, and Tips Popover, PopoverContainer, and Tips alignment values now use logical `start` / `end` instead of physical `left` / `right`. - Popover `align` and `beak` (also Coachmark `beak`): `start` | `end` | `center` - PopoverContainer `alignment`: `top-start`, `top-end`, `bottom-start`, `bottom-end`, `top`, `bottom`, `start`, `end` - ToolTip, InfoTip, and PreviewTip `alignment` (and Modal `tipAlignment`): `top-start`, `top-end`, `bottom-start`, `bottom-end`, `start-center`, `end-center`, `top-center`, `bottom-center` PopoverContainer resolves logical alignments to physical ones with `resolvePhysicalAlignment`, which replaces `mirrorAlignment`. Popover's `resolveHorizontalSideForRtl` now takes `start` / `end` and returns a physical side. Internal beak variant keys use `start` / `end`; pattern variants and beak rotations stay physical. Stories, tests, docs, and agent skills are updated to match. Code Connect files keep their current values with TODO comments until the Figma changes take effect. This also fixes two GridForm docs lines missed in the previous commit. BREAKING CHANGE: `left` and `right` are no longer accepted in these alignment values. Use `start` in place of `left` and `end` in place of `right`, e.g. `top-left` becomes `top-start` and `right-center` becomes `end-center`. Co-Authored-By: Claude Opus 5.5 --- .../.storybook/argTypes/closeButtonProps.tsx | 4 +- packages/.storybook/argTypes/infotip.tsx | 4 +- .../code-connect/Atoms/FormGroup.figma.tsx | 1 + .../Atoms/FormInputs/Radio.figma.tsx | 1 + .../Molecules/Coachmark.figma.tsx | 1 + .../code-connect/Molecules/Popover.figma.tsx | 1 + .../Molecules/Tips/InfoTip.figma.tsx | 1 + .../Molecules/Tips/PreviewTip.figma.tsx | 1 + .../Molecules/Tips/ToolTip.figma.tsx | 1 + .../skills/gamut-datatable/SKILL.md | 2 +- .../skills/gamut-menu/SKILL.md | 6 +- .../docs/components/feedback/Tips/index.mdx | 2 +- .../docs/components/feedback/Tips/infotip.mdx | 2 +- .../components/feedback/Tips/previewtip.mdx | 2 +- .../docs/components/feedback/Tips/tooltip.mdx | 4 +- .../inputs-and-forms/GridForm/patterns.mdx | 2 +- .../inputs-and-forms/GridForm/reference.mdx | 2 +- .../components/overlays/popover-container.mdx | 2 +- .../docs/components/overlays/popover.mdx | 10 +-- packages/gamut/src/Alert/Alert.stories.tsx | 2 +- .../gamut/src/Button/IconButton.stories.tsx | 2 +- .../gamut/src/Coachmark/Coachmark.stories.tsx | 6 +- .../ConnectedFormGroup.stories.tsx | 2 +- .../src/DataList/Controls/FilterControl.tsx | 2 +- .../gamut/src/DataList/DataTable.stories.tsx | 4 +- packages/gamut/src/DataList/testUtils.tsx | 8 +- .../src/DatePicker/DatePicker.stories.tsx | 2 +- packages/gamut/src/DatePicker/DatePicker.tsx | 2 +- .../src/Form/elements/FormGroup.stories.tsx | 4 +- .../gamut/src/GridForm/Layout.stories.tsx | 6 +- packages/gamut/src/Menu/Menu.stories.tsx | 24 +++--- packages/gamut/src/Menu/MenuItem.stories.tsx | 2 +- .../FloatingMenu/FloatingMenu.stories.tsx | 2 +- .../gamut/src/Popover/Popover.stories.tsx | 18 ++-- packages/gamut/src/Popover/Popover.tsx | 4 +- packages/gamut/src/Popover/elements.tsx | 5 +- .../gamut/src/Popover/styles/beak.test.ts | 28 +++--- packages/gamut/src/Popover/styles/beak.ts | 58 ++++++------- packages/gamut/src/Popover/types.tsx | 16 ++-- packages/gamut/src/Popover/utils.test.ts | 18 ++-- packages/gamut/src/Popover/utils.ts | 16 ++-- .../PopoverContainer.stories.tsx | 12 +-- .../PopoverContainer.test.tsx | 86 +++++++++---------- .../src/PopoverContainer/PopoverContainer.tsx | 2 +- packages/gamut/src/PopoverContainer/types.ts | 11 +++ packages/gamut/src/PopoverContainer/utils.ts | 56 ++++++------ .../src/Tips/InfoTip/InfoTip.stories.tsx | 12 +-- packages/gamut/src/Tips/InfoTip/index.tsx | 2 +- .../Tips/PreviewTip/PreviewTip.stories.tsx | 10 +-- packages/gamut/src/Tips/PreviewTip/index.tsx | 2 +- packages/gamut/src/Tips/PreviewTip/styles.ts | 6 +- .../src/Tips/ToolTip/ToolTip.stories.tsx | 22 ++--- .../Tips/shared/popoverAlignmentUtils.test.ts | 12 +-- .../src/Tips/shared/popoverAlignmentUtils.ts | 22 ++--- .../shared/styles/composeVariantsUtils.ts | 22 ++--- packages/gamut/src/Tips/shared/types.tsx | 12 +-- .../.storybook/argTypes/closeButtonProps.tsx | 4 +- .../.storybook/argTypes/infotip.tsx | 4 +- .../src/lib/Meta/Deep Controls add-on.mdx | 4 +- 59 files changed, 305 insertions(+), 276 deletions(-) diff --git a/packages/.storybook/argTypes/closeButtonProps.tsx b/packages/.storybook/argTypes/closeButtonProps.tsx index 06b082c554..ddd065ebbc 100644 --- a/packages/.storybook/argTypes/closeButtonProps.tsx +++ b/packages/.storybook/argTypes/closeButtonProps.tsx @@ -1,8 +1,8 @@ const tipAlignmentOptions = [ 'top-center', 'bottom-center', - 'left-center', - 'right-center', + 'start-center', + 'end-center', ] as const; export const closeButtonPropsArgTypes = ({ diff --git a/packages/.storybook/argTypes/infotip.tsx b/packages/.storybook/argTypes/infotip.tsx index e70b3aac18..6c76256484 100644 --- a/packages/.storybook/argTypes/infotip.tsx +++ b/packages/.storybook/argTypes/infotip.tsx @@ -14,9 +14,9 @@ export const infotipNestedArgTypes = { }, 'infotip.alignment': { control: 'radio', - options: ['bottom-left', 'bottom-right', 'top-left', 'top-right'], + options: ['bottom-start', 'bottom-end', 'top-start', 'top-end'], table: { - defaultValue: { summary: 'top-right' }, + defaultValue: { summary: 'top-end' }, type: { summary: 'bottom-left | bottom-right | top-left | top-right' }, }, }, diff --git a/packages/code-connect/Atoms/FormGroup.figma.tsx b/packages/code-connect/Atoms/FormGroup.figma.tsx index 47169f16db..06733c4aef 100644 --- a/packages/code-connect/Atoms/FormGroup.figma.tsx +++ b/packages/code-connect/Atoms/FormGroup.figma.tsx @@ -36,6 +36,7 @@ figma.connect( true: figma.textContent('description'), }), toolTipInfo: figma.nestedProps('.infotip-alignment', { + // TODO: Update these alignment values to their 'start' / 'end' equivalents after the Figma changes take effect. alignment: figma.enum('alignment', { 'top-left': 'top-left', 'top-right': 'top-right', diff --git a/packages/code-connect/Atoms/FormInputs/Radio.figma.tsx b/packages/code-connect/Atoms/FormInputs/Radio.figma.tsx index 86cc816655..ab076cd9be 100644 --- a/packages/code-connect/Atoms/FormInputs/Radio.figma.tsx +++ b/packages/code-connect/Atoms/FormInputs/Radio.figma.tsx @@ -41,6 +41,7 @@ figma.connect( emphasis: figma.enum('emphasis', { low: 'low', high: 'high' }), }), toolTipInfo: figma.nestedProps('.infotip-alignment', { + // TODO: Update these alignment values to their 'start' / 'end' equivalents after the Figma changes take effect. alignment: figma.enum('alignment', { 'top-left': 'top-left', 'top-right': 'top-right', diff --git a/packages/code-connect/Molecules/Coachmark.figma.tsx b/packages/code-connect/Molecules/Coachmark.figma.tsx index ddadf44312..a49a67c1e8 100644 --- a/packages/code-connect/Molecules/Coachmark.figma.tsx +++ b/packages/code-connect/Molecules/Coachmark.figma.tsx @@ -15,6 +15,7 @@ figma.connect( 'https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=19366-27764', { props: { + // TODO: Update these 'left' / 'right' values to 'start' / 'end' after the Figma changes take effect. beak: figma.enum('beak', { right: 'right', left: 'left', diff --git a/packages/code-connect/Molecules/Popover.figma.tsx b/packages/code-connect/Molecules/Popover.figma.tsx index 79a59cf15e..9a70891f5b 100644 --- a/packages/code-connect/Molecules/Popover.figma.tsx +++ b/packages/code-connect/Molecules/Popover.figma.tsx @@ -24,6 +24,7 @@ figma.connect( 'center-left': 'center', }), }), + // TODO: Update these 'left' / 'right' values to 'start' / 'end' after the Figma changes take effect. align: figma.boolean('beak', { true: figma.enum('beakPosition', { left: 'left', diff --git a/packages/code-connect/Molecules/Tips/InfoTip.figma.tsx b/packages/code-connect/Molecules/Tips/InfoTip.figma.tsx index ae69fa34da..26305ac348 100644 --- a/packages/code-connect/Molecules/Tips/InfoTip.figma.tsx +++ b/packages/code-connect/Molecules/Tips/InfoTip.figma.tsx @@ -19,6 +19,7 @@ figma.connect( high: 'high', }), toolTipInfo: figma.nestedProps('.infotip-alignment', { + // TODO: Update these alignment values to their 'start' / 'end' equivalents after the Figma changes take effect. alignment: figma.enum('alignment', { 'top-left': 'top-left', 'top-right': 'top-right', diff --git a/packages/code-connect/Molecules/Tips/PreviewTip.figma.tsx b/packages/code-connect/Molecules/Tips/PreviewTip.figma.tsx index d502d181d4..1b47dfd253 100644 --- a/packages/code-connect/Molecules/Tips/PreviewTip.figma.tsx +++ b/packages/code-connect/Molecules/Tips/PreviewTip.figma.tsx @@ -15,6 +15,7 @@ figma.connect( { props: { previewTipProps: figma.nestedProps('.previewtip-alignment-anchor', { + // TODO: Update these alignment values to their 'start' / 'end' equivalents after the Figma changes take effect. alignment: figma.enum('alignment', { 'bottom-left': 'bottom-left', 'bottom-right': 'bottom-right', diff --git a/packages/code-connect/Molecules/Tips/ToolTip.figma.tsx b/packages/code-connect/Molecules/Tips/ToolTip.figma.tsx index f09dacbdf2..3c35f828f6 100644 --- a/packages/code-connect/Molecules/Tips/ToolTip.figma.tsx +++ b/packages/code-connect/Molecules/Tips/ToolTip.figma.tsx @@ -14,6 +14,7 @@ figma.connect( 'https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=41215%3A28041', { props: { + // TODO: Update these alignment values to their 'start' / 'end' equivalents after the Figma changes take effect. alignment: figma.enum('alignment', { 'bottom-center': 'bottom-center', 'left-center': 'left-center', diff --git a/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md b/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md index 3cd4e121cf..9d833cb7b9 100644 --- a/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-datatable/SKILL.md @@ -178,7 +178,7 @@ const RowActions = ({ rowId }) => { onClick={() => setIsOpen(!isOpen)} /> @@ -138,7 +138,7 @@ Pass `label` on a `disabled` `MenuItem` to explain why it is unavailable. ```tsx Admin action @@ -151,7 +151,7 @@ Offset the `PopoverContainer` y-axis by `48` (normal spacing) or `32` (condensed ```tsx diff --git a/packages/gamut-docs/src/content/docs/components/feedback/Tips/previewtip.mdx b/packages/gamut-docs/src/content/docs/components/feedback/Tips/previewtip.mdx index 9c257ddd77..9a077aff34 100644 --- a/packages/gamut-docs/src/content/docs/components/feedback/Tips/previewtip.mdx +++ b/packages/gamut-docs/src/content/docs/components/feedback/Tips/previewtip.mdx @@ -44,6 +44,6 @@ Pass `loading` while the preview content is still being fetched: ## Playground -`alignment` accepts `top-left`, `top-right` (default), `bottom-left`, or `bottom-right`, the same corner set as `InfoTip`: +`alignment` accepts `top-start`, `top-end` (default), `bottom-start`, or `bottom-end`, the same corner set as `InfoTip`: diff --git a/packages/gamut-docs/src/content/docs/components/feedback/Tips/tooltip.mdx b/packages/gamut-docs/src/content/docs/components/feedback/Tips/tooltip.mdx index fb32198f4e..5000fa111b 100644 --- a/packages/gamut-docs/src/content/docs/components/feedback/Tips/tooltip.mdx +++ b/packages/gamut-docs/src/content/docs/components/feedback/Tips/tooltip.mdx @@ -53,10 +53,10 @@ Wrap `ToolTip` directly around any interactive element, not just `IconButton`, w ### Alignment -`alignment` accepts `top-center` (default), `bottom-center`, `left-center`, or `right-center`: +`alignment` accepts `top-center` (default), `bottom-center`, `start-center`, or `end-center`: -Under RTL layouts, `left-center`/`right-center` mirror to follow reading direction: +Under RTL layouts, `start-center`/`end-center` mirror to follow reading direction: diff --git a/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/patterns.mdx b/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/patterns.mdx index d80f18e09d..18f7c542a4 100644 --- a/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/patterns.mdx +++ b/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/patterns.mdx @@ -17,7 +17,7 @@ Use a field's `size` and `rowspan` (borrowed from [LayoutGrid](/components/conta ## Building sections -Pass section objects (each with a `title` and its own `fields`) alongside loose fields in the `fields` array. A section's `layout` can be `"left"` (title takes 3 columns) or centered (the default); `as` sets the title's heading level (default `h2`) and must be a heading tag: +Pass section objects (each with a `title` and its own `fields`) alongside loose fields in the `fields` array. A section's `layout` can be `"start"` (title takes 3 columns) or centered (the default); `as` sets the title's heading level (default `h2`) and must be a heading tag: diff --git a/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/reference.mdx b/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/reference.mdx index 0d4ec665cb..f027d36601 100644 --- a/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/reference.mdx +++ b/packages/gamut-docs/src/content/docs/components/inputs-and-forms/GridForm/reference.mdx @@ -159,7 +159,7 @@ A honeypot field — named to avoid tipping off bots that it's a spam trap, unli ### Position -`submit.position` picks its alignment: `'left'` (default), `'center'`, `'right'`, or `'stretch'`. +`submit.position` picks its alignment: `'start'` (default), `'center'`, `'end'`, or `'stretch'`. #### Left diff --git a/packages/gamut-docs/src/content/docs/components/overlays/popover-container.mdx b/packages/gamut-docs/src/content/docs/components/overlays/popover-container.mdx index c1ea327051..8c7588c350 100644 --- a/packages/gamut-docs/src/content/docs/components/overlays/popover-container.mdx +++ b/packages/gamut-docs/src/content/docs/components/overlays/popover-container.mdx @@ -34,7 +34,7 @@ Use `PopoverContainer` when you need Gamut's floating-positioning logic without ### Alignment -`alignment` accepts a target edge (`'top'`, `'bottom'`, `'left'`, `'right'`) or corner (`'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`), default `'bottom-left'`: +`alignment` accepts a target edge (`'top'`, `'bottom'`, `'start'`, `'end'`) or corner (`'top-start'`, `'top-end'`, `'bottom-start'`, `'bottom-end'`), default `'bottom-start'`: diff --git a/packages/gamut-docs/src/content/docs/components/overlays/popover.mdx b/packages/gamut-docs/src/content/docs/components/overlays/popover.mdx index 5abf4e6fe9..37c6835978 100644 --- a/packages/gamut-docs/src/content/docs/components/overlays/popover.mdx +++ b/packages/gamut-docs/src/content/docs/components/overlays/popover.mdx @@ -15,7 +15,7 @@ Use `Popover` for interactive floating content anchored to a target element — - `Popover` is controlled: pass `isOpen` and a `targetRef` pointing at the element it's anchored to. - It closes itself automatically if its target scrolls fully out of the viewport — that's always on, not configurable, unlike [PopoverContainer](/components/overlays/popover-container/)'s opt-in `closeOnViewportExit`. -- `align`, `position`, and `beak` are RTL-aware — under `GamutProvider`'s logical properties, `left`/`right` follow reading direction rather than fixed physical sides. +- `align`, `position`, and `beak` are RTL-aware — under `GamutProvider`'s logical properties, `start`/`end` follow reading direction rather than fixed physical sides. **When NOT to use:** @@ -24,7 +24,7 @@ Use `Popover` for interactive floating content anchored to a target element — ### Anatomy -1. **Beak** (optional, `beak`) — a pointed triangle connecting the popover to its target; pass `left`/`right` to pin a corner, or `center` for a centered triangle. +1. **Beak** (optional, `beak`) — a pointed triangle connecting the popover to its target; pass `start`/`end` to pin a corner, or `center` for a centered triangle. 2. **Pattern background** (optional, `pattern`) — a decorative pattern layer; unavailable when `position="center"`. 3. **Content** — `children`. @@ -46,7 +46,7 @@ When a popover's content has nothing to focus, the popover itself becomes the fa ### Position -`position` (`'above'`, `'below'`, or `'center'`) and `align` (`'left'`, `'right'`, or `'center'`) together place the popover relative to `targetRef`. +`position` (`'above'`, `'below'`, or `'center'`) and `align` (`'start'`, `'end'`, or `'center'`) together place the popover relative to `targetRef`. #### Above @@ -56,11 +56,11 @@ When a popover's content has nothing to focus, the popover itself becomes the fa -#### Center, aligned left +#### Center, aligned start -#### Center, aligned right +#### Center, aligned end diff --git a/packages/gamut/src/Alert/Alert.stories.tsx b/packages/gamut/src/Alert/Alert.stories.tsx index bd56981462..6de75e9413 100644 --- a/packages/gamut/src/Alert/Alert.stories.tsx +++ b/packages/gamut/src/Alert/Alert.stories.tsx @@ -291,7 +291,7 @@ export const CloseButtonCustomization: Story = { closeButtonProps={{ tip: 'Wow, a left-aligned tooltip!', ref: closeButtonRef, - tipAlignment: 'left-center', + tipAlignment: 'start-center', }} type="feature" onClose={() => setIsVisible(false)} diff --git a/packages/gamut/src/Button/IconButton.stories.tsx b/packages/gamut/src/Button/IconButton.stories.tsx index e9218b4b12..3f3d9af2df 100644 --- a/packages/gamut/src/Button/IconButton.stories.tsx +++ b/packages/gamut/src/Button/IconButton.stories.tsx @@ -44,7 +44,7 @@ const meta: TypeWithDeepControls> = { }, 'tipProps.alignment': { control: 'radio', - options: ['top-center', 'bottom-center', 'left-center', 'right-center'], + options: ['top-center', 'bottom-center', 'start-center', 'end-center'], }, }, }; diff --git a/packages/gamut/src/Coachmark/Coachmark.stories.tsx b/packages/gamut/src/Coachmark/Coachmark.stories.tsx index c367db0e4e..2d45d840cc 100644 --- a/packages/gamut/src/Coachmark/Coachmark.stories.tsx +++ b/packages/gamut/src/Coachmark/Coachmark.stories.tsx @@ -27,7 +27,7 @@ const meta: TypeWithDeepControls> = { }, 'popoverProps.beak': { control: 'radio', - options: ['left', 'right', 'center'], + options: ['start', 'end', 'center'], table: { type: { summary: 'left | right | center', @@ -62,7 +62,7 @@ const meta: TypeWithDeepControls> = { }, 'popoverProps.align': { control: 'radio', - options: ['left', 'right', 'center'], + options: ['start', 'end', 'center'], table: { type: { summary: 'left | right | center', @@ -158,7 +158,7 @@ export const Delay: Story = { export const Customized: Story = { args: { popoverProps: { - beak: 'left', + beak: 'start', outline: true, pattern: patterns.CheckerDense, position: 'above', diff --git a/packages/gamut/src/ConnectedForm/ConnectedFormGroup.stories.tsx b/packages/gamut/src/ConnectedForm/ConnectedFormGroup.stories.tsx index 39193bfa7f..e2f04ebce0 100644 --- a/packages/gamut/src/ConnectedForm/ConnectedFormGroup.stories.tsx +++ b/packages/gamut/src/ConnectedForm/ConnectedFormGroup.stories.tsx @@ -163,7 +163,7 @@ export const InfoTipWithReactNodeLabel: Story = { = ({ {menuOpen && ( { icon={MiniKebabMenuIcon} tip="Show options" tipProps={{ - alignment: 'left-center', + alignment: 'start-center', placement: 'floating', }} variant="secondary" onClick={() => setIsOpen(!isOpen)} /> { icon={MiniKebabMenuIcon} tip="Show options" tipProps={{ - alignment: 'left-center', + alignment: 'start-center', placement: 'floating', }} variant="secondary" onClick={() => setIsOpen(!isOpen)} /> [] = [ {' '} ), diff --git a/packages/gamut/src/DatePicker/DatePicker.stories.tsx b/packages/gamut/src/DatePicker/DatePicker.stories.tsx index 1630499afb..57afcd68d7 100644 --- a/packages/gamut/src/DatePicker/DatePicker.stories.tsx +++ b/packages/gamut/src/DatePicker/DatePicker.stories.tsx @@ -667,7 +667,7 @@ const ComposedDatePickerLayout: React.FC = () => { = (props) => { )} , @@ -124,7 +124,7 @@ export const HighEmphasisInfoTip: Story = { htmlFor: 'high-emphasis-input', infotip: { emphasis: 'high', - alignment: 'bottom-left', + alignment: 'bottom-start', info: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', }, children: , diff --git a/packages/gamut/src/GridForm/Layout.stories.tsx b/packages/gamut/src/GridForm/Layout.stories.tsx index 1bef73018d..d550eb1edc 100644 --- a/packages/gamut/src/GridForm/Layout.stories.tsx +++ b/packages/gamut/src/GridForm/Layout.stories.tsx @@ -135,7 +135,7 @@ export const InfoTip: Story = { { infotip: { info: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', - alignment: 'bottom-left', + alignment: 'bottom-start', }, label: 'Tool input', name: 'input-field', @@ -145,7 +145,7 @@ export const InfoTip: Story = { { infotip: { info: , - alignment: 'bottom-right', + alignment: 'bottom-end', }, label: 'Select with infotip', options: ['', 'Water', 'Earth', 'Fire', 'Air', 'Boomerang'], @@ -195,7 +195,7 @@ export const InfoTip: Story = { { infotip: { info: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.', - alignment: 'bottom-right', + alignment: 'bottom-end', }, label: 'End User License Agreement', description: 'I promise that I read it', diff --git a/packages/gamut/src/Menu/Menu.stories.tsx b/packages/gamut/src/Menu/Menu.stories.tsx index 34b47e8c1c..4275eef6f8 100644 --- a/packages/gamut/src/Menu/Menu.stories.tsx +++ b/packages/gamut/src/Menu/Menu.stories.tsx @@ -79,7 +79,7 @@ export const Popover: Story = { icon={MultipleUsersIcon} label={{ info: 'More info here...', - alignment: 'right-center', + alignment: 'end-center', }} onClick={() => null} > @@ -92,7 +92,7 @@ export const Popover: Story = { disabled label={{ info: 'This is disabled because...', - alignment: 'right-center', + alignment: 'end-center', }} onClick={() => null} > @@ -121,7 +121,7 @@ export const Fixed: Story = { icon={MultipleUsersIcon} label={{ info: 'More info here...', - alignment: 'right-center', + alignment: 'end-center', }} onClick={() => null} > @@ -134,7 +134,7 @@ export const Fixed: Story = { disabled label={{ info: 'This is disabled because...', - alignment: 'right-center', + alignment: 'end-center', }} onClick={() => null} > @@ -285,14 +285,14 @@ export const IconOnly: Story = { {}} /> {}} /> {}} @@ -301,14 +301,14 @@ export const IconOnly: Story = { active href="#whatsup-1" icon={FileIcon} - label={{ alignment: 'right-center', info: 'Learn' }} + label={{ alignment: 'end-center', info: 'Learn' }} /> I am bold and different, narrow: true, }} @@ -316,7 +316,7 @@ export const IconOnly: Story = { ), @@ -335,14 +335,14 @@ export const FloatingMenu: Story = { const target = useRef(null); const [isOpen, setIsOpen] = useState(false); const [currentTarget, setCurrentTarget] = useState(0); - const [alignment, setAlignment] = useState<'top-right' | 'bottom-right'>( - 'top-right' + const [alignment, setAlignment] = useState<'top-end' | 'bottom-end'>( + 'top-end' ); const [activeIndex, setActiveIndex] = useState(4); const clickHandler = (targetNumber: number, currentIndex: number) => { setCurrentTarget(targetNumber); - setAlignment(currentIndex === 3 ? 'bottom-right' : 'top-right'); + setAlignment(currentIndex === 3 ? 'bottom-end' : 'top-end'); if (isOpen && currentIndex === activeIndex) { setIsOpen(false); diff --git a/packages/gamut/src/Menu/MenuItem.stories.tsx b/packages/gamut/src/Menu/MenuItem.stories.tsx index 8f54aa5766..23d1706f49 100644 --- a/packages/gamut/src/Menu/MenuItem.stories.tsx +++ b/packages/gamut/src/Menu/MenuItem.stories.tsx @@ -109,7 +109,7 @@ export const ToolTipLabels: Story = { Link with object label diff --git a/packages/gamut/src/Patterns/FloatingMenu/FloatingMenu.stories.tsx b/packages/gamut/src/Patterns/FloatingMenu/FloatingMenu.stories.tsx index 33d68f3057..ed45407327 100644 --- a/packages/gamut/src/Patterns/FloatingMenu/FloatingMenu.stories.tsx +++ b/packages/gamut/src/Patterns/FloatingMenu/FloatingMenu.stories.tsx @@ -47,7 +47,7 @@ export const Default: Story = { /> , + render: (args) => , play: async (context) => { await openPopover(context); screen.getByTestId('popover-beak'); @@ -144,7 +144,7 @@ export const CenterLeft: Story = { render: (args) => ( ( @@ -299,7 +299,7 @@ export const PositionBelowLeft: Story = { }; export const PositionAboveRight: Story = { - args: { position: 'above', align: 'right' }, + args: { position: 'above', align: 'end' }, render: renderCentered, play: async (context) => { await openPopover(context); @@ -355,7 +355,7 @@ export const ScrolledOutOfView: Story = { export const RtlAlignLeft: Story = { tags: ['!autodocs'], globals: { direction: 'rtl' }, - args: { align: 'left' }, + args: { align: 'start' }, render: renderCentered, play: async (context) => { await expect(document.documentElement).toHaveAttribute('dir', 'rtl'); @@ -370,7 +370,7 @@ export const RtlAlignLeft: Story = { export const RtlAlignRight: Story = { tags: ['!autodocs'], globals: { direction: 'rtl' }, - args: { align: 'right' }, + args: { align: 'end' }, render: renderCentered, play: async (context) => { await openPopover(context); @@ -385,7 +385,7 @@ export const RtlCenterAlignLeft: Story = { tags: ['!autodocs'], globals: { direction: 'rtl' }, args: { - align: 'left', + align: 'start', beak: 'center', position: 'center', variant: 'secondary', @@ -406,7 +406,7 @@ export const RtlCenterAlignRight: Story = { tags: ['!autodocs'], globals: { direction: 'rtl' }, args: { - align: 'right', + align: 'end', beak: 'center', position: 'center', variant: 'secondary', diff --git a/packages/gamut/src/Popover/Popover.tsx b/packages/gamut/src/Popover/Popover.tsx index 40aa6e48a5..e44fc12df5 100755 --- a/packages/gamut/src/Popover/Popover.tsx +++ b/packages/gamut/src/Popover/Popover.tsx @@ -22,7 +22,7 @@ import { getDefaultOffset, resolveHorizontalSideForRtl } from './utils'; export const Popover: React.FC = ({ animation, - align = 'left', + align = 'start', beak, children, className, @@ -57,7 +57,7 @@ export const Popover: React.FC = ({ // This only needs to resolve the positioning - the beak uses logical properties so will automatically mirror in RTL. const resolvedSideAlign = useMemo(() => { - if (align !== 'left' && align !== 'right') return align; + if (align === 'center') return align; return resolveHorizontalSideForRtl({ side: align, isRtl, diff --git a/packages/gamut/src/Popover/elements.tsx b/packages/gamut/src/Popover/elements.tsx index abef619eb3..78b298fb2b 100644 --- a/packages/gamut/src/Popover/elements.tsx +++ b/packages/gamut/src/Popover/elements.tsx @@ -74,7 +74,10 @@ export const PopoverPortal: React.FC< ); -export type PopoverContainerProps = Pick; +export type PopoverContainerProps = Pick & { + /** Physical side resolved from `PopoverProps['align']`. */ + align?: 'left' | 'right' | 'center'; +}; export const PopoverContainer = styled.div` position: fixed; diff --git a/packages/gamut/src/Popover/styles/beak.test.ts b/packages/gamut/src/Popover/styles/beak.test.ts index 6265937dee..7ebfc2c609 100644 --- a/packages/gamut/src/Popover/styles/beak.test.ts +++ b/packages/gamut/src/Popover/styles/beak.test.ts @@ -5,39 +5,39 @@ describe('getBeakVariant', () => { expect( getBeakVariant({ position: 'below', - align: 'right', - beak: 'left', + align: 'end', + beak: 'start', variant: 'primary', }) - ).toBe('below-left'); + ).toBe('below-start'); }); it("uses `beak` when `position` is not `center` (i.e. `above`) to set the location of the beak relative to the popover' container", () => { expect( getBeakVariant({ position: 'above', - align: 'left', - beak: 'right', + align: 'start', + beak: 'end', variant: 'primary', }) - ).toBe('above-right'); + ).toBe('above-end'); }); it('uses `align` for the beak position when `position` is `above`/`below` when beak is explicitly omitted', () => { expect( getBeakVariant({ position: 'above', - align: 'right', + align: 'end', variant: 'secondary', }) - ).toBe('above-right-sml'); + ).toBe('above-end-sml'); }); it('uses center beak when beak is center regardless of align', () => { expect( getBeakVariant({ position: 'below', - align: 'right', + align: 'end', beak: 'center', variant: 'primary', }) @@ -48,21 +48,21 @@ describe('getBeakVariant', () => { expect( getBeakVariant({ position: 'center', - align: 'left', + align: 'start', beak: 'center', variant: 'secondary', }) - ).toBe('center-left-sml'); + ).toBe('center-start-sml'); }); it('appends -sml for secondary variant', () => { expect( getBeakVariant({ position: 'below', - align: 'right', - beak: 'left', + align: 'end', + beak: 'start', variant: 'secondary', }) - ).toBe('below-left-sml'); + ).toBe('below-start-sml'); }); }); diff --git a/packages/gamut/src/Popover/styles/beak.ts b/packages/gamut/src/Popover/styles/beak.ts index 15f4a2057e..b01dcee71d 100644 --- a/packages/gamut/src/Popover/styles/beak.ts +++ b/packages/gamut/src/Popover/styles/beak.ts @@ -108,22 +108,22 @@ export const beakBoxY = { }; export const beakVariantsArray = [ - 'below-left', - 'below-right', + 'below-start', + 'below-end', 'below-center', - 'above-left', - 'above-right', + 'above-start', + 'above-end', 'above-center', - 'below-left-sml', - 'below-right-sml', + 'below-start-sml', + 'below-end-sml', 'below-center-sml', - 'above-left-sml', - 'above-right-sml', + 'above-start-sml', + 'above-end-sml', 'above-center-sml', - 'center-right', - 'center-left', - 'center-left-sml', - 'center-right-sml', + 'center-end', + 'center-start', + 'center-start-sml', + 'center-end-sml', ]; export const getBeakVariant = ({ @@ -133,16 +133,16 @@ export const getBeakVariant = ({ variant, }: Pick) => { const suffix = variant === 'secondary' ? '-sml' : ''; - let beakAlignment: 'left' | 'right' | 'center'; + let beakAlignment: 'start' | 'end' | 'center'; if (position === 'center') { - beakAlignment = align ?? 'left'; + beakAlignment = align ?? 'start'; } else if (beak === 'center') { beakAlignment = 'center'; - } else if (beak === 'left' || beak === 'right') { + } else if (beak === 'start' || beak === 'end') { beakAlignment = beak; } else { - beakAlignment = align === 'left' ? 'left' : 'right'; + beakAlignment = align === 'start' ? 'start' : 'end'; } return `${position}-${beakAlignment}${suffix}`; @@ -153,7 +153,7 @@ export const createBeakVariantFromAlignment = (alignment: string) => { const isSml = alignment.includes('sml'); const isAbove = alignment.includes('above'); const isBelow = alignment.includes('below'); - const isRight = alignment.includes('right'); + const isEnd = alignment.includes('-end'); const isXCentered = alignment.includes('-center'); const isYCentered = alignment.startsWith('center-'); @@ -161,14 +161,14 @@ export const createBeakVariantFromAlignment = (alignment: string) => { if (isYCentered) { // center-x-sml styleObject = { ...beakYCenterSml }; - if (isRight) { - // center-right-sml + if (isEnd) { + // center-end-sml styleObject = { ...styleObject, ...beakRightCenterStylesSml, }; } else { - // center-left-sml + // center-start-sml styleObject = { ...styleObject, ...beakLeftCenterStylesSml, @@ -182,8 +182,8 @@ export const createBeakVariantFromAlignment = (alignment: string) => { // below-x-sml styleObject = { ...positionBelowSml }; } - if (isRight) { - // above-right-sml + below-right-sml + if (isEnd) { + // above-end-sml + below-end-sml styleObject = { ...styleObject, ...beakRightSml }; } else if (isXCentered) { // above-center-sml + below-center-sml @@ -196,18 +196,18 @@ export const createBeakVariantFromAlignment = (alignment: string) => { styleObject = { ...styleObject, ...beakBottomStyles }; } } else { - // above-left-sml + below-left-sml + // above-start-sml + below-start-sml styleObject = { ...styleObject, ...beakLeftSml }; } } } else if (isYCentered) { // center-x styleObject = { ...beakYCenter }; - if (isRight) { - // center-right + if (isEnd) { + // center-end styleObject = { ...styleObject, ...beakRightCenterStylesLrg }; } else { - // center-left + // center-start styleObject = { ...styleObject, ...beakLeftCenterStylesLrg }; } } else { @@ -218,14 +218,14 @@ export const createBeakVariantFromAlignment = (alignment: string) => { // below-x styleObject = { ...positionBelow }; } - if (isRight) { - // above-right + below-right + if (isEnd) { + // above-end + below-end styleObject = { ...styleObject, ...beakRight }; } else if (isXCentered) { // above-center + below-center styleObject = { ...styleObject, ...beakXCenter }; } else { - // above-left + below-left + // above-start + below-start styleObject = { ...styleObject, ...beakLeft }; } } diff --git a/packages/gamut/src/Popover/types.tsx b/packages/gamut/src/Popover/types.tsx index 333e2d60f8..3ff2208cd9 100755 --- a/packages/gamut/src/Popover/types.tsx +++ b/packages/gamut/src/Popover/types.tsx @@ -39,11 +39,11 @@ export type PopoverYPositionType = { position?: 'above' | 'below'; /** * Renders the beak. For `above` / `below`, use `center` for a centered triangle; pass - * `left` or `right` to pin the corner beak (or omit to derive the corner from `align`). - * With `GamutProvider`’s `useLogicalProperties` and an RTL target, `left` / `right` are - * mirrored the same way as `align` (logical start / end). + * `start` or `end` to pin the corner beak (or omit to derive the corner from `align`). + * With `GamutProvider`’s `useLogicalProperties` and an RTL target, `start` / `end` are + * mirrored the same way as `align`. */ - beak?: 'left' | 'right' | 'center'; + beak?: 'start' | 'end' | 'center'; /** * Pattern component to use as a background. */ @@ -80,12 +80,12 @@ export type PopoverProps = PopoverBaseProps & className?: string; /** * Horizontal alignment of the popover relative to the target. When - * `GamutProvider`'s `useLogicalProperties` is enabled, `left` and `right` follow the - * inline axis (leading/trailing): under RTL they resolve to the physical side that - * matches inline-start and inline-end, consistent with `useElementDir` on `targetRef`. + * `GamutProvider`'s `useLogicalProperties` is enabled, `start` and `end` follow the + * inline axis: under RTL they resolve to the physical side that matches + * inline-start and inline-end, consistent with `useElementDir` on `targetRef`. * Applies for all `position` values (`above`, `below`, `center`). */ - align?: 'left' | 'right' | 'center'; + align?: 'start' | 'end' | 'center'; /** * Number of pixels to offset the popover vertically from the source component. */ diff --git a/packages/gamut/src/Popover/utils.test.ts b/packages/gamut/src/Popover/utils.test.ts index d8c65f44c5..3c8f705d62 100644 --- a/packages/gamut/src/Popover/utils.test.ts +++ b/packages/gamut/src/Popover/utils.test.ts @@ -3,49 +3,49 @@ import { resolveHorizontalSideForRtl } from './utils'; describe('resolveHorizontalSideForRtl', () => { it.each([ { - side: 'left' as const, + side: 'start' as const, isRtl: false, useLogicalProperties: false, expected: 'left', }, { - side: 'right' as const, + side: 'end' as const, isRtl: false, useLogicalProperties: false, expected: 'right', }, { - side: 'left' as const, + side: 'start' as const, isRtl: true, useLogicalProperties: false, expected: 'left', }, { - side: 'right' as const, + side: 'end' as const, isRtl: true, useLogicalProperties: false, expected: 'right', }, { - side: 'left' as const, + side: 'start' as const, isRtl: false, useLogicalProperties: true, expected: 'left', }, { - side: 'right' as const, + side: 'end' as const, isRtl: false, useLogicalProperties: true, expected: 'right', }, { - side: 'left' as const, + side: 'start' as const, isRtl: true, useLogicalProperties: true, expected: 'right', }, { - side: 'right' as const, + side: 'end' as const, isRtl: true, useLogicalProperties: true, expected: 'left', @@ -62,7 +62,7 @@ describe('resolveHorizontalSideForRtl', () => { it('treats undefined useLogicalProperties like false', () => { expect( resolveHorizontalSideForRtl({ - side: 'left', + side: 'start', isRtl: true, useLogicalProperties: undefined, }) diff --git a/packages/gamut/src/Popover/utils.ts b/packages/gamut/src/Popover/utils.ts index 9e0c593c3e..6db52e3538 100644 --- a/packages/gamut/src/Popover/utils.ts +++ b/packages/gamut/src/Popover/utils.ts @@ -1,13 +1,14 @@ import type { PopoverProps } from './types'; /** - * Mirrors horizontal `left` / `right` in RTL when `useLogicalProperties` is enabled - * (Popover `align` / `beak` resolution). `Popover` passes `isRtl` from + * Resolves a logical `start` / `end` side to a physical `left` / `right` side + * (Popover `align` resolution). `start` is `left` unless `useLogicalProperties` is + * enabled and the element is RTL. `Popover` passes `isRtl` from * `useElementDir(targetRef)` and document `dir` (see `Popover` implementation). - * @param side - The horizontal side to resolve. + * @param side - The logical horizontal side to resolve. * @param isRtl - Whether the element is in an RTL context. * @param useLogicalProperties - Whether logical properties are enabled. - * @returns The resolved horizontal side. + * @returns The resolved physical horizontal side. * WARNING : Do not use this function to swap elements that use css logical properties. They will get double-mirrored. */ export const resolveHorizontalSideForRtl = ({ @@ -15,12 +16,13 @@ export const resolveHorizontalSideForRtl = ({ isRtl, useLogicalProperties, }: { - side: 'left' | 'right'; + side: 'start' | 'end'; isRtl: boolean; useLogicalProperties: boolean | undefined; }): 'left' | 'right' => { - if (!useLogicalProperties) return side; - return isRtl ? (side === 'left' ? 'right' : 'left') : side; + const mirrored = Boolean(useLogicalProperties) && isRtl; + if (side === 'start') return mirrored ? 'right' : 'left'; + return mirrored ? 'left' : 'right'; }; const offsets = { diff --git a/packages/gamut/src/PopoverContainer/PopoverContainer.stories.tsx b/packages/gamut/src/PopoverContainer/PopoverContainer.stories.tsx index b627a2f907..f9d84af11c 100644 --- a/packages/gamut/src/PopoverContainer/PopoverContainer.stories.tsx +++ b/packages/gamut/src/PopoverContainer/PopoverContainer.stories.tsx @@ -10,7 +10,7 @@ const meta: Meta = { title: 'Overlays/PopoverContainer', component: PopoverContainer, args: { - alignment: 'top-left', + alignment: 'top-start', allowPageInteraction: true, isOpen: true, inline: true, @@ -66,13 +66,13 @@ const meta: Meta = { export default meta; type Story = StoryObj; -const SINGLE_DIRECTIONS = ['top', 'bottom', 'left', 'right'] as const; +const SINGLE_DIRECTIONS = ['top', 'bottom', 'start', 'end'] as const; const MULTI_DIRECTIONS = [ - 'top-left', - 'top-right', - 'bottom-right', - 'bottom-left', + 'top-start', + 'top-end', + 'bottom-end', + 'bottom-start', ] as const; export const Default: Story = { diff --git a/packages/gamut/src/PopoverContainer/PopoverContainer.test.tsx b/packages/gamut/src/PopoverContainer/PopoverContainer.test.tsx index a75a4c1141..a484b1c593 100644 --- a/packages/gamut/src/PopoverContainer/PopoverContainer.test.tsx +++ b/packages/gamut/src/PopoverContainer/PopoverContainer.test.tsx @@ -221,17 +221,17 @@ describe('Popover', () => { PopoverContainerProps['alignment'], Record ][] = [ - ['top-right', { left: '370px', bottom: '-130px' }], - ['top-left', { right: '370px', bottom: '-130px' }], - ['bottom-right', { left: '370px', top: '370px' }], - ['bottom-left', { right: '370px', top: '370px' }], + ['top-end', { left: '370px', bottom: '-130px' }], + ['top-start', { right: '370px', bottom: '-130px' }], + ['bottom-end', { left: '370px', top: '370px' }], + ['bottom-start', { right: '370px', top: '370px' }], // 'top'/'bottom' center horizontally using a physical screen coordinate, // so the horizontal position is always physical `left` regardless of // useLogicalProperties — placement stays inline style, not variance props. ['top', { left: '250px', bottom: '-130px' }], - ['left', { right: '370px', top: '250px' }], + ['start', { right: '370px', top: '250px' }], ['bottom', { left: '250px', top: '370px' }], - ['right', { left: '370px', top: '250px' }], + ['end', { left: '370px', top: '250px' }], ]; alignmentTests.forEach(([alignment, expected]) => { @@ -261,15 +261,15 @@ describe('Popover', () => { PopoverContainerProps['alignment'], Record ][] = [ - ['top-right', { left: '370px', bottom: '370px' }], - ['top-left', { right: '370px', bottom: '370px' }], - ['bottom-right', { left: '370px', top: '370px' }], - ['bottom-left', { right: '370px', top: '370px' }], + ['top-end', { left: '370px', bottom: '370px' }], + ['top-start', { right: '370px', bottom: '370px' }], + ['bottom-end', { left: '370px', top: '370px' }], + ['bottom-start', { right: '370px', top: '370px' }], // See comment above re: physical 'left' for centered alignments. ['top', { left: '250px', bottom: '370px' }], - ['left', { right: '370px', top: '250px' }], + ['start', { right: '370px', top: '250px' }], ['bottom', { left: '250px', top: '370px' }], - ['right', { left: '370px', top: '250px' }], + ['end', { left: '370px', top: '250px' }], ]; alignmentTests.forEach(([alignment, expected]) => { @@ -295,14 +295,14 @@ describe('Popover', () => { describe('edges', () => { describe('outside', () => { it.each([ - ['top-right', 'translate(0, 0)'], - ['top-left', 'translate(0, 0)'], - ['bottom-right', 'translate(0, 0)'], - ['bottom-left', 'translate(0, 0)'], + ['top-end', 'translate(0, 0)'], + ['top-start', 'translate(0, 0)'], + ['bottom-end', 'translate(0, 0)'], + ['bottom-start', 'translate(0, 0)'], ['top', 'translate(-50%, 0)'], - ['left', 'translate(0, -50%)'], + ['start', 'translate(0, -50%)'], ['bottom', 'translate(-50%, 0)'], - ['right', 'translate(0, -50%)'], + ['end', 'translate(0, -50%)'], ] as const)( '%s', (alignment: PopoverContainerProps['alignment'], expected: string) => { @@ -315,14 +315,14 @@ describe('Popover', () => { }); describe('inside', () => { it.each([ - ['top-right', 'translate(-100%, 0)'], - ['top-left', 'translate(100%, 0)'], - ['bottom-right', 'translate(-100%, 0)'], - ['bottom-left', 'translate(100%, 0)'], + ['top-end', 'translate(-100%, 0)'], + ['top-start', 'translate(100%, 0)'], + ['bottom-end', 'translate(-100%, 0)'], + ['bottom-start', 'translate(100%, 0)'], ['top', 'translate(-50%, 0)'], - ['left', 'translate(0, -50%)'], + ['start', 'translate(0, -50%)'], ['bottom', 'translate(-50%, 0)'], - ['right', 'translate(0, -50%)'], + ['end', 'translate(0, -50%)'], ] as const)( '%s', (alignment: PopoverContainerProps['alignment'], expected: string) => { @@ -348,12 +348,12 @@ describe('Popover', () => { const base = { container, offset: 20, x: 0, y: 0 }; it.each([ - ['bottom-left', 'bottom-right'], - ['bottom-right', 'bottom-left'], - ['top-left', 'top-right'], - ['top-right', 'top-left'], - ['left', 'right'], - ['right', 'left'], + ['bottom-start', 'bottom-end'], + ['bottom-end', 'bottom-start'], + ['top-start', 'top-end'], + ['top-end', 'top-start'], + ['start', 'end'], + ['end', 'start'], ] as const)('RTL %s matches LTR %s', (rtlPlacement, ltrMirror) => { expect( utils.getPosition({ @@ -416,14 +416,14 @@ describe('Popover', () => { }; it.each([ - ['top-right', false, 'translate(-100%, 0)'], - ['top-right', true, 'translate(100%, 0)'], - ['top-left', false, 'translate(100%, 0)'], - ['top-left', true, 'translate(-100%, 0)'], - ['bottom-right', false, 'translate(-100%, 0)'], - ['bottom-right', true, 'translate(100%, 0)'], - ['bottom-left', false, 'translate(100%, 0)'], - ['bottom-left', true, 'translate(-100%, 0)'], + ['top-end', false, 'translate(-100%, 0)'], + ['top-end', true, 'translate(100%, 0)'], + ['top-start', false, 'translate(100%, 0)'], + ['top-start', true, 'translate(-100%, 0)'], + ['bottom-end', false, 'translate(-100%, 0)'], + ['bottom-end', true, 'translate(100%, 0)'], + ['bottom-start', false, 'translate(100%, 0)'], + ['bottom-start', true, 'translate(-100%, 0)'], ] as const)( '%s invertAxis="x" isRtl=%s → %s', (alignment, isRtl, expected) => { @@ -440,12 +440,12 @@ describe('Popover', () => { describe('transform is always applied as a physical inline style', () => { it.each([ - [true, 'top-right', 'translate(0, 0)'], - [false, 'top-right', 'translate(0, 0)'], + [true, 'top-end', 'translate(0, 0)'], + [false, 'top-end', 'translate(0, 0)'], [true, 'top', 'translate(-50%, 0)'], [false, 'top', 'translate(-50%, 0)'], - [true, 'left', 'translate(0, -50%)'], - [false, 'left', 'translate(0, -50%)'], + [true, 'start', 'translate(0, -50%)'], + [false, 'start', 'translate(0, -50%)'], ] as const)( 'useLogicalProperties=%s, alignment=%s → transform: %s', (useLogicalProperties, alignment, expected) => { @@ -490,7 +490,7 @@ describe('Popover', () => { = ({ - alignment = 'bottom-left', + alignment = 'bottom-start', offset = 20, y = 0, x = 0, diff --git a/packages/gamut/src/PopoverContainer/types.ts b/packages/gamut/src/PopoverContainer/types.ts index 3d5db77685..90672495b8 100644 --- a/packages/gamut/src/PopoverContainer/types.ts +++ b/packages/gamut/src/PopoverContainer/types.ts @@ -4,6 +4,17 @@ import type { FocusTrapProps } from '../FocusTrap'; import type { WithChildrenProp } from '../utils'; export type PopoverContainerAlignment = + | 'top-start' + | 'top-end' + | 'bottom-start' + | 'bottom-end' + | 'top' + | 'bottom' + | 'start' + | 'end'; + +/** Physical placement {@link PopoverContainerAlignment} resolves to for position math. */ +export type PopoverContainerPhysicalAlignment = | 'top-left' | 'top-right' | 'bottom-left' diff --git a/packages/gamut/src/PopoverContainer/utils.ts b/packages/gamut/src/PopoverContainer/utils.ts index 8c97fa8ad0..37d273095b 100644 --- a/packages/gamut/src/PopoverContainer/utils.ts +++ b/packages/gamut/src/PopoverContainer/utils.ts @@ -1,40 +1,46 @@ import type { CSSObject } from '@skillsoft/variance'; import { percentageOrAbsolute as percent } from '@skillsoft/variance'; -import type { PopoverContainerAlignment, PopoverPositionConfig } from './types'; +import type { + PopoverContainerAlignment, + PopoverContainerPhysicalAlignment, + PopoverPositionConfig, +} from './types'; export interface PopoverPositionResult { /** Edge insets pinning the popover to the container (`left` / `right` / `top` / `bottom`). */ styles: CSSObject; /** * Direction-neutral transforms/coords—semantic mirroring happens first via - * {@link mirrorAlignment}; merged after `styles`. + * {@link resolvePhysicalAlignment}; merged after `styles`. */ dirNeutralStyles?: CSSObject; } /** - * Mirrors placement on the inline axis when the target is RTL so e.g. `bottom-left` - * uses the same geometry as `bottom-right` in LTR. + * Resolves a logical placement to its physical placement on the inline axis: + * `start` is `left` in LTR and `right` in RTL, e.g. `bottom-start` uses the same + * geometry as `bottom-right` in LTR when the target is RTL. */ -export const mirrorAlignment = ( +export const resolvePhysicalAlignment = ( alignment: PopoverContainerAlignment, isRtl: boolean -): PopoverContainerAlignment => { - if (!isRtl) return alignment; +): PopoverContainerPhysicalAlignment => { + const start = isRtl ? 'right' : 'left'; + const end = isRtl ? 'left' : 'right'; switch (alignment) { - case 'top-left': - return 'top-right'; - case 'top-right': - return 'top-left'; - case 'bottom-left': - return 'bottom-right'; - case 'bottom-right': - return 'bottom-left'; - case 'left': - return 'right'; - case 'right': - return 'left'; + case 'top-start': + return `top-${start}`; + case 'top-end': + return `top-${end}`; + case 'bottom-start': + return `bottom-${start}`; + case 'bottom-end': + return `bottom-${end}`; + case 'start': + return start; + case 'end': + return end; default: return alignment; } @@ -200,16 +206,16 @@ const AXIS = { /** * Computes the absolute position styles for a popover relative to a target element. * - * When `isRtl` is true, {@link mirrorAlignment} maps the requested placement to the - * mirrored corner/edge on the inline axis before computing offsets (same viewport math - * as LTR). + * {@link resolvePhysicalAlignment} maps the requested logical placement to a physical + * corner/edge on the inline axis (mirrored when `isRtl` is true) before computing + * offsets (same viewport math as LTR). * * Returns two fragments that callers merge into inline `style` (they are not Gamut variance * props on the host, so nothing here is swapped to logical properties via `system.positioning`). * * - `styles`: corner/edge inset lengths (`left` / `right` / `top` / `bottom`). * - `dirNeutralStyles`: transforms/coords not further remapped for RTL/logical placement - * after {@link mirrorAlignment}; merged after `styles`. + * after {@link resolvePhysicalAlignment}; merged after `styles`. */ export const getPosition = ({ alignment, @@ -220,7 +226,7 @@ export const getPosition = ({ invertAxis, isRtl = false, }: PopoverPositionConfig & { isRtl?: boolean }): PopoverPositionResult => { - const layoutAlignment = mirrorAlignment(alignment, isRtl); + const layoutAlignment = resolvePhysicalAlignment(alignment, isRtl); const { top, left, bottom, right, height, width } = container; const xOffset = width + offset + x; const yOffset = height + offset + y; @@ -237,7 +243,7 @@ export const getPosition = ({ const isVertical = direction === 'top' || direction === 'bottom'; if (isVertical) { - // Center x uses viewport/layout coords — stays literal after mirrorAlignment under RTL. + // Center x uses viewport/layout coords — stays literal after resolvePhysicalAlignment under RTL. dirNeutralStyles.left = left + width / 2; dirNeutralStyles.transform = 'translate(-50%, 0)'; } else { diff --git a/packages/gamut/src/Tips/InfoTip/InfoTip.stories.tsx b/packages/gamut/src/Tips/InfoTip/InfoTip.stories.tsx index c276f25405..32b83de01c 100644 --- a/packages/gamut/src/Tips/InfoTip/InfoTip.stories.tsx +++ b/packages/gamut/src/Tips/InfoTip/InfoTip.stories.tsx @@ -16,7 +16,7 @@ const meta: Meta = { title: 'Feedback/Tips/InfoTip', component: InfoTip, args: { - alignment: 'top-left', + alignment: 'top-start', ariaLabel: 'More information', info: `I am additional information about a nearby element or content.`, onClick: fn(), @@ -192,7 +192,7 @@ export const Emphasis: Story = { export const Alignments: Story = { render: (args) => ( - {(['top-right', 'top-left', 'bottom-right', 'bottom-left'] as const).map( + {(['top-end', 'top-start', 'bottom-end', 'bottom-start'] as const).map( (alignment) => { const labelId = `alignment-${alignment}`; return ( @@ -219,7 +219,7 @@ export const Alignments: Story = { await expectAllClosed(buttons); await openInfoTipsWithKeyboard(context, buttons); - await userEvent.click(canvas.getByText('top-right')); + await userEvent.click(canvas.getByText('top-end')); await expectAllClosed(buttons); }, }; @@ -291,7 +291,7 @@ export const AriaLabel: Story = { I am some helpful yet concise text that needs more explanation @@ -319,7 +319,7 @@ export const FloatingAriaLabel: Story = { export const CustomRoleDescription: Story = { args: { ariaRoleDescription: 'Botón de más información', - alignment: 'top-right', + alignment: 'top-end', placement: 'floating', }, play: async ({ canvas }) => { @@ -413,7 +413,7 @@ export const KeyboardNavigation: Story = { { title: 'Inline Placement', placement: 'inline' as const, - alignment: 'bottom-right' as const, + alignment: 'bottom-end' as const, links: ['Link A', 'Link B'], }, ]; diff --git a/packages/gamut/src/Tips/InfoTip/index.tsx b/packages/gamut/src/Tips/InfoTip/index.tsx index 226ab0e52e..fae929b120 100644 --- a/packages/gamut/src/Tips/InfoTip/index.tsx +++ b/packages/gamut/src/Tips/InfoTip/index.tsx @@ -69,7 +69,7 @@ const MODAL_SELECTOR = 'dialog[open],[role="dialog"]:not([aria-hidden="true"]),[role="alertdialog"]:not([aria-hidden="true"])'; export const InfoTip: React.FC = ({ - alignment = 'top-right', + alignment = 'top-end', ariaLabel, ariaLabelledby, ariaRoleDescription = 'More information button', diff --git a/packages/gamut/src/Tips/PreviewTip/PreviewTip.stories.tsx b/packages/gamut/src/Tips/PreviewTip/PreviewTip.stories.tsx index 649885151c..35c8daa694 100644 --- a/packages/gamut/src/Tips/PreviewTip/PreviewTip.stories.tsx +++ b/packages/gamut/src/Tips/PreviewTip/PreviewTip.stories.tsx @@ -12,7 +12,7 @@ const meta: Meta = { title: 'Feedback/Tips/PreviewTip', component: PreviewTip, args: { - alignment: 'bottom-right', + alignment: 'bottom-end', children: 'PreviewTip Anchor', linkDescription, href: 'https://media0.giphy.com/media/v1.Y2lkPTc5MGI3NjExamp6NDVlZzNpam01NnlhaGRreWMwZGlzZ3Z6bWd2dmtneTJrN3pnZiZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/X5Lta1bjuULTubmGzR/giphy.webp', @@ -66,7 +66,7 @@ const LoadingExample = () => { I am a perpetually loading preview. { const TruncationExample = (args: React.ComponentProps) => { return ( - + @@ -136,7 +136,7 @@ export const AvatarTip: Story = { export const FloatingPreviewTip: Story = { args: { placement: 'floating', - alignment: 'top-right', + alignment: 'top-end', }, play: async ({ args, canvas, userEvent }) => { const link = canvas.getByRole('link', { name: 'PreviewTip Anchor' }); diff --git a/packages/gamut/src/Tips/PreviewTip/index.tsx b/packages/gamut/src/Tips/PreviewTip/index.tsx index 10e2ab87fb..5f9e28dd52 100644 --- a/packages/gamut/src/Tips/PreviewTip/index.tsx +++ b/packages/gamut/src/Tips/PreviewTip/index.tsx @@ -21,7 +21,7 @@ export type PreviewTipProps = ComponentProps & linkDescription: string; }; export const PreviewTip: React.FC = ({ - alignment = 'top-right', + alignment = 'top-end', avatar, children, linkDescription, diff --git a/packages/gamut/src/Tips/PreviewTip/styles.ts b/packages/gamut/src/Tips/PreviewTip/styles.ts index e4bcb33072..7d729327c5 100644 --- a/packages/gamut/src/Tips/PreviewTip/styles.ts +++ b/packages/gamut/src/Tips/PreviewTip/styles.ts @@ -8,12 +8,12 @@ export const defaultGridTemplate = `1fr`; export const getShadowAlignment = (alignment: string) => { const topAligned = alignment.includes('top'); - const leftAligned = alignment.includes('left'); + const startAligned = alignment.includes('start'); return { bottom: !topAligned ? shadowAlignment : undefined, - left: leftAligned ? shadowAlignment : undefined, - right: !leftAligned ? shadowAlignment : undefined, + left: startAligned ? shadowAlignment : undefined, + right: !startAligned ? shadowAlignment : undefined, top: topAligned ? shadowAlignment : undefined, }; }; diff --git a/packages/gamut/src/Tips/ToolTip/ToolTip.stories.tsx b/packages/gamut/src/Tips/ToolTip/ToolTip.stories.tsx index b6d79ad45d..4e5ad76de4 100644 --- a/packages/gamut/src/Tips/ToolTip/ToolTip.stories.tsx +++ b/packages/gamut/src/Tips/ToolTip/ToolTip.stories.tsx @@ -24,8 +24,8 @@ type Story = StoryObj; const alignments = [ 'top-center', 'bottom-center', - 'left-center', - 'right-center', + 'start-center', + 'end-center', ] as const; const onTipTargetClick = fn(); @@ -99,7 +99,7 @@ export const WithIconButton: Story = { ), @@ -174,7 +174,7 @@ export const InteractiveElement: Story = { ), diff --git a/packages/gamut/src/Tips/shared/popoverAlignmentUtils.test.ts b/packages/gamut/src/Tips/shared/popoverAlignmentUtils.test.ts index aa457d1d3b..83b2606376 100644 --- a/packages/gamut/src/Tips/shared/popoverAlignmentUtils.test.ts +++ b/packages/gamut/src/Tips/shared/popoverAlignmentUtils.test.ts @@ -1,28 +1,28 @@ import { getPopoverAlignmentAndPattern } from './popoverAlignmentUtils'; describe('getPopoverAlignmentAndPattern', () => { - it('maps left-center to Popover center + align left', () => { + it('maps start-center to Popover center + align start', () => { expect( getPopoverAlignmentAndPattern({ - alignment: 'left-center', + alignment: 'start-center', type: 'tool', }) ).toMatchObject({ position: 'center', - align: 'left', + align: 'start', beak: 'center', }); }); - it('maps right-center to Popover center + align right', () => { + it('maps end-center to Popover center + align end', () => { expect( getPopoverAlignmentAndPattern({ - alignment: 'right-center', + alignment: 'end-center', type: 'tool', }) ).toMatchObject({ position: 'center', - align: 'right', + align: 'end', beak: 'center', }); }); diff --git a/packages/gamut/src/Tips/shared/popoverAlignmentUtils.ts b/packages/gamut/src/Tips/shared/popoverAlignmentUtils.ts index 3b982cf7b3..fa5a188a55 100644 --- a/packages/gamut/src/Tips/shared/popoverAlignmentUtils.ts +++ b/packages/gamut/src/Tips/shared/popoverAlignmentUtils.ts @@ -14,20 +14,20 @@ export const getAlignmentStyles = ({ }: Pick) => { if (avatar) return 'avatarAligned'; if (type === 'preview') return 'previewAligned'; - if (alignment.startsWith('left') || alignment.startsWith('right')) + if (alignment.startsWith('start') || alignment.startsWith('end')) return 'horizontalCenter'; return alignment.includes('center') ? 'vertCenter' : 'aligned'; }; export const getPopoverAlignmentAndPattern = ({ - alignment = 'top-left', + alignment = 'top-start', type, }: Partial>): | (PopoverXPositionType & Pick) | (PopoverYPositionType & Pick) => { const popoverAlignment: PopoverYPositionType & Pick = { - align: 'right', - beak: 'right', + align: 'end', + beak: 'end', position: 'above', pattern: undefined, }; @@ -44,11 +44,11 @@ export const getPopoverAlignmentAndPattern = ({ popoverAlignment.beak = 'center'; } - if (alignment.includes('right-') || alignment.includes('left-')) { - if (alignment.includes('left-')) { - popoverAlignment.align = 'left'; + if (alignment.startsWith('start-') || alignment.startsWith('end-')) { + if (alignment.startsWith('start-')) { + popoverAlignment.align = 'start'; } else { - popoverAlignment.align = 'right'; + popoverAlignment.align = 'end'; } return { beak: 'center', @@ -59,9 +59,9 @@ export const getPopoverAlignmentAndPattern = ({ if (alignment.includes('bottom')) popoverAlignment.position = 'below'; - if (alignment.includes('-right')) { - popoverAlignment.align = 'left'; - popoverAlignment.beak = 'left'; + if (alignment.endsWith('-end')) { + popoverAlignment.align = 'start'; + popoverAlignment.beak = 'start'; } return popoverAlignment; diff --git a/packages/gamut/src/Tips/shared/styles/composeVariantsUtils.ts b/packages/gamut/src/Tips/shared/styles/composeVariantsUtils.ts index fc7bfb00ee..41a5ea6d6b 100644 --- a/packages/gamut/src/Tips/shared/styles/composeVariantsUtils.ts +++ b/packages/gamut/src/Tips/shared/styles/composeVariantsUtils.ts @@ -30,33 +30,33 @@ export const createToolTipVariantFromAlignment = (alignment: string) => { let styleObjectAfter = {}; let styleObjectBefore = {}; - const isRight = alignment.includes('right'); + const isEnd = alignment.startsWith('end') || alignment.endsWith('-end'); const isTop = alignment.includes('top'); const isCenter = alignment.includes('center'); const isBottom = alignment.includes('bottom'); const isLRAligned = - alignment.startsWith('right') || alignment.startsWith('left'); + alignment.startsWith('end') || alignment.startsWith('start'); - // top-center, top-right, + top-left styles + // top-center, top-end, + top-start styles if (isTop) { styleObject = { ...topStyles }; styleObjectAfter = { ...topStylesAfter }; styleObjectBefore = { ...topStylesBefore }; - // bottom-center, bottom-right, + bottom-left styles + // bottom-center, bottom-end, + bottom-start styles } else if (isBottom) { styleObject = { ...bottomStyles }; styleObjectAfter = { ...bottomStylesAfter }; styleObjectBefore = { ...bottomStylesBefore }; } else if (isLRAligned) { - // right-center & left-center styles + // end-center & start-center styles styleObject = { ...horizontalCenterStyles }; styleObjectAfter = { ...centerHorizontal }; styleObjectBefore = { ...beforeStylesHorizontal }; - // right-center styles - if (isRight) { + // end-center styles + if (isEnd) { styleObject = { ...styleObject, ...rightAlignStyles }; styleObjectAfter = { ...styleObjectAfter, ...rightAlignStylesAfter }; - // left-center styles + // start-center styles } else { styleObject = { ...styleObject, ...leftAlignStyles }; styleObjectAfter = { ...styleObjectAfter, ...leftAlignStylesAfter }; @@ -68,12 +68,12 @@ export const createToolTipVariantFromAlignment = (alignment: string) => { styleObject = { ...styleObject, ...verticalCenterStyles }; styleObjectAfter = { ...styleObjectAfter, ...verticalCenterStylesAfter }; } else if (!isCenter && !isLRAligned) { - // top-right, bottom-right - if (isRight) { + // top-end, bottom-end + if (isEnd) { styleObject = { ...styleObject, ...rightVertStyles }; styleObjectAfter = { ...styleObjectAfter, ...rightVertStylesAfter }; } else { - // top-left, bottom-left + // top-start, bottom-start styleObject = { ...styleObject, ...leftVertStyles }; styleObjectAfter = { ...styleObjectAfter, ...leftVertStylesAfter }; } diff --git a/packages/gamut/src/Tips/shared/types.tsx b/packages/gamut/src/Tips/shared/types.tsx index 8bffa36b83..b1bc4e1739 100644 --- a/packages/gamut/src/Tips/shared/types.tsx +++ b/packages/gamut/src/Tips/shared/types.tsx @@ -3,16 +3,16 @@ import type { ComponentProps, ReactNode } from 'react'; import type { Text } from '../../Typography'; export const tipBaseAlignmentArray = [ - 'bottom-left', - 'bottom-right', - 'top-left', - 'top-right', + 'bottom-start', + 'bottom-end', + 'top-start', + 'top-end', ] as const; const tipCenterAlignmentArray = [ 'bottom-center', - 'left-center', - 'right-center', + 'start-center', + 'end-center', 'top-center', ] as const; diff --git a/packages/styleguide/.storybook/argTypes/closeButtonProps.tsx b/packages/styleguide/.storybook/argTypes/closeButtonProps.tsx index 06b082c554..ddd065ebbc 100644 --- a/packages/styleguide/.storybook/argTypes/closeButtonProps.tsx +++ b/packages/styleguide/.storybook/argTypes/closeButtonProps.tsx @@ -1,8 +1,8 @@ const tipAlignmentOptions = [ 'top-center', 'bottom-center', - 'left-center', - 'right-center', + 'start-center', + 'end-center', ] as const; export const closeButtonPropsArgTypes = ({ diff --git a/packages/styleguide/.storybook/argTypes/infotip.tsx b/packages/styleguide/.storybook/argTypes/infotip.tsx index e70b3aac18..6c76256484 100644 --- a/packages/styleguide/.storybook/argTypes/infotip.tsx +++ b/packages/styleguide/.storybook/argTypes/infotip.tsx @@ -14,9 +14,9 @@ export const infotipNestedArgTypes = { }, 'infotip.alignment': { control: 'radio', - options: ['bottom-left', 'bottom-right', 'top-left', 'top-right'], + options: ['bottom-start', 'bottom-end', 'top-start', 'top-end'], table: { - defaultValue: { summary: 'top-right' }, + defaultValue: { summary: 'top-end' }, type: { summary: 'bottom-left | bottom-right | top-left | top-right' }, }, }, diff --git a/packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx b/packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx index c4f2ff63f2..6c6dbc970e 100644 --- a/packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx +++ b/packages/styleguide/src/lib/Meta/Deep Controls add-on.mdx @@ -199,9 +199,9 @@ export const infotipNestedArgTypes = { }, 'infotip.alignment': { control: 'radio', - options: ['bottom-left', 'bottom-right', 'top-left', 'top-right'], + options: ['bottom-start', 'bottom-end', 'top-start', 'top-end'], table: { - defaultValue: { summary: 'top-right' }, + defaultValue: { summary: 'top-end' }, type: { summary: 'bottom-left | bottom-right | top-left | top-right' }, }, }, From 51d3a9582b74cc4f870a89f6a55967fee3d51373 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 14:50:26 -0500 Subject: [PATCH 3/9] fix: use logical start/end keywords for text and flex alignment Physical `left` / `right` CSS keyword values now use logical `start` / `end`, so they flip in RTL. - SelectDropdown option label `textAlign` - DataList SortControl `textAlign` - ProgressBar percent label `text-align` - BarChart and Menu story alignment - Storybook TableOfContents and ImageGallery `textAlign` LTR rendering is unchanged. Co-Authored-By: Claude Opus 5.5 --- packages/.storybook/components/Elements/ImageGallery.tsx | 2 +- packages/gamut/src/BarChart/BarChart.stories.tsx | 2 +- packages/gamut/src/DataList/Controls/SortControl.tsx | 2 +- .../gamut/src/Form/inputs/SelectDropdown/elements/options.tsx | 2 +- packages/gamut/src/Menu/Menu.stories.tsx | 2 +- packages/gamut/src/ProgressBar/index.tsx | 2 +- .../styleguide/.storybook/components/Elements/ImageGallery.tsx | 2 +- .../.storybook/components/Navigation/TableOfContents.tsx | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/.storybook/components/Elements/ImageGallery.tsx b/packages/.storybook/components/Elements/ImageGallery.tsx index d234f051e9..f91bd4aa40 100644 --- a/packages/.storybook/components/Elements/ImageGallery.tsx +++ b/packages/.storybook/components/Elements/ImageGallery.tsx @@ -213,7 +213,7 @@ export const ImageGallery: React.FC = ({ > - + {name} diff --git a/packages/gamut/src/BarChart/BarChart.stories.tsx b/packages/gamut/src/BarChart/BarChart.stories.tsx index c78d323f66..8741818fbd 100644 --- a/packages/gamut/src/BarChart/BarChart.stories.tsx +++ b/packages/gamut/src/BarChart/BarChart.stories.tsx @@ -491,7 +491,7 @@ export const WithExternalTitle: Story = { borderRadius="lg" id="external-chart-title" p={16} - textAlign="right" + textAlign="end" > Programming Skills Overview diff --git a/packages/gamut/src/DataList/Controls/SortControl.tsx b/packages/gamut/src/DataList/Controls/SortControl.tsx index 201bd06e1e..b8e4fccdeb 100644 --- a/packages/gamut/src/DataList/Controls/SortControl.tsx +++ b/packages/gamut/src/DataList/Controls/SortControl.tsx @@ -11,7 +11,7 @@ import type { OnSort, SortDirection, SortOrder } from '../types'; const SortAnchor = styled(Anchor)( css({ color: 'text', - textAlign: 'left', + textAlign: 'start', width: '100%', alignItems: 'flex-end', '&:hover': { diff --git a/packages/gamut/src/Form/inputs/SelectDropdown/elements/options.tsx b/packages/gamut/src/Form/inputs/SelectDropdown/elements/options.tsx index aeef639823..d74c12bacf 100644 --- a/packages/gamut/src/Form/inputs/SelectDropdown/elements/options.tsx +++ b/packages/gamut/src/Form/inputs/SelectDropdown/elements/options.tsx @@ -122,7 +122,7 @@ export const formatOptionLabel = ({ fontSize={14} justifyContent="flex-end" pr={16} - textAlign="right" + textAlign="end" > {rightLabel} diff --git a/packages/gamut/src/Menu/Menu.stories.tsx b/packages/gamut/src/Menu/Menu.stories.tsx index 4275eef6f8..f806f57242 100644 --- a/packages/gamut/src/Menu/Menu.stories.tsx +++ b/packages/gamut/src/Menu/Menu.stories.tsx @@ -362,7 +362,7 @@ export const FloatingMenu: Story = { bg="navy" dimensions="200px" height="100%" - justifyContent="right" + justifyContent="end" ref={target} > diff --git a/packages/gamut/src/ProgressBar/index.tsx b/packages/gamut/src/ProgressBar/index.tsx index 05c0edb710..add3bf4769 100644 --- a/packages/gamut/src/ProgressBar/index.tsx +++ b/packages/gamut/src/ProgressBar/index.tsx @@ -157,7 +157,7 @@ const Bar = styled(Box)(progressBarForegroundVariants); const DisplayedPercent = styled.span` font-weight: bold; padding: 0.5rem; - text-align: right; + text-align: end; width: 100%; `; diff --git a/packages/styleguide/.storybook/components/Elements/ImageGallery.tsx b/packages/styleguide/.storybook/components/Elements/ImageGallery.tsx index d234f051e9..f91bd4aa40 100644 --- a/packages/styleguide/.storybook/components/Elements/ImageGallery.tsx +++ b/packages/styleguide/.storybook/components/Elements/ImageGallery.tsx @@ -213,7 +213,7 @@ export const ImageGallery: React.FC = ({ > - + {name} diff --git a/packages/styleguide/.storybook/components/Navigation/TableOfContents.tsx b/packages/styleguide/.storybook/components/Navigation/TableOfContents.tsx index e6a1c78e05..e81a290fb0 100644 --- a/packages/styleguide/.storybook/components/Navigation/TableOfContents.tsx +++ b/packages/styleguide/.storybook/components/Navigation/TableOfContents.tsx @@ -67,7 +67,7 @@ export const TopicCard: React.FC = ({ p={24} position={'relative'} rowGap={8} - textAlign={'left'} + textAlign="start" > From 3af5db186b4d4b7b46042638658affde8a0b5314 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 15:04:08 -0500 Subject: [PATCH 4/9] docs: explain start/end prop values in naming conventions The naming conventions rationale page now explains why prop values use `start` / `end` instead of `left` / `right`, and why `start` / `end` is preferred over `leading` / `trailing` for values. The writing guidance page links to the rationale page and updates the RTL rule to cover prop values. The rule no longer says `start` / `end` replace `top` / `bottom`, which contradicted the renamed values. Co-Authored-By: Claude Opus 5.5 --- .../content/docs/concepts/naming-conventions-rationale.md | 6 ++++++ .../gamut-docs/src/content/docs/guides/writing-guidance.md | 7 +++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md b/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md index e2729eec5d..87a8c02b8a 100644 --- a/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md +++ b/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md @@ -31,6 +31,12 @@ Let's explore using an example: `hideLabel` on `ConnectedFormGroup` has no defau A property named `left` means something different once a page mirrors for a right-to-left locale — the padding or margin a developer set for one side silently lands on the other. `leading`/`trailing` and `start`/`end` name a position relative to the reading direction instead of the screen, so the same prop value is correct in both directions with no conditional logic to flip it. +The same reasoning applies to prop values, so props like `iconPosition`, `align`, `alignment`, and `justify` take `start` and `end` rather than `left` and `right`. `iconPosition="start"` places the icon before the label, and it stays accurate on a mirrored page. `iconPosition="left"` would put the icon in the same place but describe it wrongly, since in a right-to-left layout the icon renders on the right. Compound placements change only their inline half: `top-left` becomes `top-start`, and `right-center` becomes `end-center`. + +For values, we use `start`/`end` instead of `leading`/`trailing` because many of them pass straight through to CSS, where `text-align: start` and `justify-content: end` are valid and `leading` isn't. A DataList column's `justify` value, for example, goes directly to the cell's `textAlign` with no lookup table in between. + +Physical sides still exist inside the implementation. `Popover` and `PopoverContainer` measure the target in physical screen coordinates, so they resolve `start` to `left` or `right` from the target's reading direction before positioning. Callers only ever pass the logical value. + ## Names you can act on `Container` and `Wrapper` describe the shape of the code, not what it's for. Both just mean something wraps something else. Six months later, nobody can tell from the name alone whether it's safe to delete, safe to reuse, or load-bearing for three other components. `SkipToContent` or `RadialProgress` answers that question on sight. Matching the folder, file, and export to the same name keeps that answer one lookup away, whether someone arrives at the file through an import statement, a fuzzy search, or jump-to-definition. diff --git a/packages/gamut-docs/src/content/docs/guides/writing-guidance.md b/packages/gamut-docs/src/content/docs/guides/writing-guidance.md index 74ff400f45..4d84f10252 100644 --- a/packages/gamut-docs/src/content/docs/guides/writing-guidance.md +++ b/packages/gamut-docs/src/content/docs/guides/writing-guidance.md @@ -7,6 +7,8 @@ description: Naming, comment, formatting, and linking conventions for Gamut code We’ve established these conventions to help provide guidance on one of the most difficult exercises in programming — naming. These guidelines are not hard and fast rules, they won’t cover every single case, but generally, they will provide a frame of mind to write helpful names for anyone reading this code, including agents. +The [Naming conventions rationale](/concepts/naming-conventions-rationale/) page explains the reasoning behind the conventions that aren't self-evident. + ### Principles 1. Be readable - ensure that the name can be understood by other people, not just your current self. @@ -39,8 +41,9 @@ We’ve established these conventions to help provide guidance on one of the mos - Name the state for which the component is usually in, and default to that state - `visible` (defaulting to `true`) beats `hidden` (defaulting to `false`) when a component is visible most of the time. - Name what the prop controls, not how it's built. `size="sm"`, not `smallVariant` or `useSmallStyles`. -- Opt for logical property names instead of physical or visual names to allow for RTL conversions - — `leading`/`trailing` over `left`/`right`, `start`/`end` over `top`/`bottom` +- Opt for logical names instead of physical or visual names so props stay correct in right-to-left (RTL) layouts. This applies to prop values as well as prop names. + - e.g. `start`/`end` over `left`/`right`: `iconPosition="start"`, `alignment="top-end"`, `labelSide="end"` + - See the [reading-direction rationale](/concepts/naming-conventions-rationale/#staying-correct-in-both-reading-directions) for why values use `start`/`end` rather than `leading`/`trailing`. **Variables and constants** From eb36190d881e65b7fa87dfc8726fb1f4cefca659 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 15:09:11 -0500 Subject: [PATCH 5/9] add changeset --- .changeset/spotty-lilies-shout.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/spotty-lilies-shout.md diff --git a/.changeset/spotty-lilies-shout.md b/.changeset/spotty-lilies-shout.md new file mode 100644 index 0000000000..30201aa08d --- /dev/null +++ b/.changeset/spotty-lilies-shout.md @@ -0,0 +1,6 @@ +--- +'@skillsoft/gamut': minor +'@skillsoft/gamut-agent-tools': minor +--- + +Update props to use start/end in place of left/right From ce2e5915ca5e159562dfda836e1ccfbefcd090e4 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 16:15:04 -0500 Subject: [PATCH 6/9] fix up stories to reflect start/end --- .../src/content/docs/components/actions/toggle.mdx | 4 ++-- packages/gamut/src/List/ListCol.stories.tsx | 4 ++-- packages/gamut/src/Toggle/Toggle.stories.tsx | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/gamut-docs/src/content/docs/components/actions/toggle.mdx b/packages/gamut-docs/src/content/docs/components/actions/toggle.mdx index 3f6b7b96f1..e4ba03cb4f 100644 --- a/packages/gamut-docs/src/content/docs/components/actions/toggle.mdx +++ b/packages/gamut-docs/src/content/docs/components/actions/toggle.mdx @@ -56,8 +56,8 @@ Pass a `ReactNode` to `label` when the label needs its own markup or styling — ### Label side - - + + ### Disabled diff --git a/packages/gamut/src/List/ListCol.stories.tsx b/packages/gamut/src/List/ListCol.stories.tsx index a6a99782d9..fff2539783 100644 --- a/packages/gamut/src/List/ListCol.stories.tsx +++ b/packages/gamut/src/List/ListCol.stories.tsx @@ -184,10 +184,10 @@ export const Justification: ListCompositionStory = { - Left + Start - Right + End diff --git a/packages/gamut/src/Toggle/Toggle.stories.tsx b/packages/gamut/src/Toggle/Toggle.stories.tsx index 6c3565d4df..66df127760 100644 --- a/packages/gamut/src/Toggle/Toggle.stories.tsx +++ b/packages/gamut/src/Toggle/Toggle.stories.tsx @@ -61,16 +61,16 @@ export const DisabledChecked: Story = { }, }; -export const LabelLeft: Story = { +export const LabelStart: Story = { args: { - label: 'My label is to the left', + label: 'My label placed on `start`', labelSide: 'start', }, }; -export const LabelRight: Story = { +export const LabelEnd: Story = { args: { - label: 'My label is to the right', + label: 'My label placed on `end`', labelSide: 'end', }, }; From 97755978dc85bf1ac683a68bce5a6fdbd095785c Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 16:20:56 -0500 Subject: [PATCH 7/9] docs: restructure reading-direction rationale The "Staying correct in both reading directions" section now explains the `start` / `end` values Gamut uses and why, then the `left` / `right` values they replaced and why those no longer suit RTL layouts. Co-Authored-By: Claude Opus 5.5 --- .../content/docs/concepts/naming-conventions-rationale.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md b/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md index 87a8c02b8a..ba2ea96d69 100644 --- a/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md +++ b/packages/gamut-docs/src/content/docs/concepts/naming-conventions-rationale.md @@ -29,11 +29,13 @@ Let's explore using an example: `hideLabel` on `ConnectedFormGroup` has no defau ## Staying correct in both reading directions -A property named `left` means something different once a page mirrors for a right-to-left locale — the padding or margin a developer set for one side silently lands on the other. `leading`/`trailing` and `start`/`end` name a position relative to the reading direction instead of the screen, so the same prop value is correct in both directions with no conditional logic to flip it. +Gamut prop values name inline positions with `start` and `end`: `iconPosition="start"`, `labelSide="end"`, `menuAlignment="end"`. Compound placements make only their inline half logical, so `PopoverContainer` takes `alignment="top-start"` and `ToolTip` takes `alignment="end-center"`. `start` is the side where reading begins, which is the left in a left-to-right (LTR) layout and the right in a right-to-left (RTL) layout. Because the value names a position relative to the reading direction instead of the screen, the same value is correct in both directions with no conditional logic in the calling code. -The same reasoning applies to prop values, so props like `iconPosition`, `align`, `alignment`, and `justify` take `start` and `end` rather than `left` and `right`. `iconPosition="start"` places the icon before the label, and it stays accurate on a mirrored page. `iconPosition="left"` would put the icon in the same place but describe it wrongly, since in a right-to-left layout the icon renders on the right. Compound placements change only their inline half: `top-left` becomes `top-start`, and `right-center` becomes `end-center`. +We use `start`/`end` instead of `leading`/`trailing` because many of these values pass straight through to CSS, where `text-align: start` and `justify-content: end` are valid and `leading` isn't. A DataList column's `justify` value, for example, goes directly to the cell's `textAlign` with no lookup table in between. -For values, we use `start`/`end` instead of `leading`/`trailing` because many of them pass straight through to CSS, where `text-align: start` and `justify-content: end` are valid and `leading` isn't. A DataList column's `justify` value, for example, goes directly to the cell's `textAlign` with no lookup table in between. +These values used to be `left` and `right`: `iconPosition="left"`, `buttonPlacement="right"`, `alignment="top-left"`. They named a side of the screen, which held up as long as every page read left to right. + +Gamut now supports RTL layouts through `GamutProvider`'s `useLogicalProperties`, and physical names break there. On a mirrored page, an icon set with `iconPosition="left"` renders on the right, so the value describes the wrong side. Components that mirror their placement had to document `left` as meaning the start side, and the `Popover` component's `align` docs did exactly that, leaving the name and the behavior in disagreement. With `start` and `end`, the name matches what renders in either direction. Physical sides still exist inside the implementation. `Popover` and `PopoverContainer` measure the target in physical screen coordinates, so they resolve `start` to `left` or `right` from the target's reading direction before positioning. Callers only ever pass the logical value. From e9cb42da9159285f42fd04263cdf065ca821bf39 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Mon, 16 Nov 2026 16:30:03 -0500 Subject: [PATCH 8/9] fix broken storybook test --- packages/gamut/src/List/ListCol.stories.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/gamut/src/List/ListCol.stories.tsx b/packages/gamut/src/List/ListCol.stories.tsx index fff2539783..d6eb525eaa 100644 --- a/packages/gamut/src/List/ListCol.stories.tsx +++ b/packages/gamut/src/List/ListCol.stories.tsx @@ -194,10 +194,10 @@ export const Justification: ListCompositionStory = { ); }, play: async ({ canvas }) => { - await expect(canvas.getByText('Left')).toHaveStyle({ + await expect(canvas.getByText('Start')).toHaveStyle({ justifyContent: 'flex-start', }); - await expect(canvas.getByText('Right')).toHaveStyle({ + await expect(canvas.getByText('End')).toHaveStyle({ justifyContent: 'flex-end', }); }, From ac3797ecfbb0a85440c937072689a6e3d07db62d Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 20 Nov 2026 16:38:57 -0500 Subject: [PATCH 9/9] fix: use start/end in InfoTip alignment argTypes summary Co-Authored-By: Claude Opus 5.5 --- packages/.storybook/argTypes/infotip.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/.storybook/argTypes/infotip.tsx b/packages/.storybook/argTypes/infotip.tsx index 6c76256484..475bfbeeee 100644 --- a/packages/.storybook/argTypes/infotip.tsx +++ b/packages/.storybook/argTypes/infotip.tsx @@ -17,7 +17,7 @@ export const infotipNestedArgTypes = { options: ['bottom-start', 'bottom-end', 'top-start', 'top-end'], table: { defaultValue: { summary: 'top-end' }, - type: { summary: 'bottom-left | bottom-right | top-left | top-right' }, + type: { summary: 'bottom-start | bottom-end | top-start | top-end' }, }, }, 'infotip.placement': {