diff --git a/apps/docs/content/docs/components/layout/aspect-ratio.mdx b/apps/docs/content/docs/components/layout/aspect-ratio.mdx new file mode 100644 index 00000000..f90eed7b --- /dev/null +++ b/apps/docs/content/docs/components/layout/aspect-ratio.mdx @@ -0,0 +1,26 @@ +--- +title: Aspect ratio +description: Lock media to an inline-to-block ratio. +source: packages/@luke-ui/react/src/exports/aspect-ratio.ts +--- + +`AspectRatio` locks a frame to an inline-to-block ratio and sizes its direct child to fill the +frame. Use it for media such as an `iframe`, `img`, or `video`. Images and videos use +`objectFit="cover"` by default. Pass another `objectFit` value to change how they fit the frame. +Read [Layout](/docs/layout#choose-a-layout-component) to choose a layout component. + + + +## Choose the rendered element + +AspectRatio uses +[Box's `elementType` and `render` contract](/components/layout/box#choose-the-rendered-element). + + + +## API + + diff --git a/apps/docs/content/docs/components/layout/container.mdx b/apps/docs/content/docs/components/layout/container.mdx new file mode 100644 index 00000000..6ed0babd --- /dev/null +++ b/apps/docs/content/docs/components/layout/container.mdx @@ -0,0 +1,37 @@ +--- +title: Container +description: Constrain content and establish a local size container. +source: packages/@luke-ui/react/src/exports/container.ts +--- + +`Container` fills its available inline size up to `maxInlineSize` and centres itself. Pass a `ct` +value for a fixed maximum, or a CSS length. Pass `marginInline` to change the centring. Read +[Layout](/docs/layout#choose-a-layout-component) to choose a layout component. + + + +## Responsive descendants + +A traditional container usually only constrains and centres content. Luke UI's `Container` also +establishes a local responsive query boundary. + +Luke UI responsive values inside the Container resolve against its content box rather than the +document root. A `ct672` Container therefore never reaches `bp768`. `paddingInline` reduces the +content-box width, so it can also change where responsive styles switch. + +Use Container when descendants should respond to the available content area rather than the document +root. + +## Choose the rendered element + +Container uses +[Box's `elementType` and `render` contract](/components/layout/box#choose-the-rendered-element). + + + +## API + + diff --git a/apps/docs/content/docs/components/layout/meta.json b/apps/docs/content/docs/components/layout/meta.json index 21c89362..0aa86caa 100644 --- a/apps/docs/content/docs/components/layout/meta.json +++ b/apps/docs/content/docs/components/layout/meta.json @@ -1,4 +1,4 @@ { "title": "Layout", - "pages": ["box", "cluster", "stack", "visually-hidden"] + "pages": ["aspect-ratio", "box", "cluster", "container", "stack", "visually-hidden"] } diff --git a/apps/docs/content/docs/components/meta.json b/apps/docs/content/docs/components/meta.json index 7966f5a1..3d616beb 100644 --- a/apps/docs/content/docs/components/meta.json +++ b/apps/docs/content/docs/components/meta.json @@ -15,8 +15,10 @@ "forms/combobox-field", "forms/text-field", "---Layout---", + "layout/aspect-ratio", "layout/box", "layout/cluster", + "layout/container", "layout/stack", "layout/visually-hidden", "---Typography---", diff --git a/apps/docs/content/docs/docs/layout.mdx b/apps/docs/content/docs/docs/layout.mdx index 9ddb83d8..f7903b15 100644 --- a/apps/docs/content/docs/docs/layout.mdx +++ b/apps/docs/content/docs/docs/layout.mdx @@ -5,11 +5,13 @@ description: Build responsive structure with layout utilities and breakpoints. ## Choose a layout component -| Component | Use when | -| ------------------------------------- | --------------------------------------------------------------- | -| [Stack](/components/layout/stack) | Direct children should flow on the logical block axis | -| [Cluster](/components/layout/cluster) | Direct children should flow on the logical inline axis and wrap | -| [Box](/components/layout/box) | You need a custom flex or grid layout, or visual utilities | +| Component | Use when | +| ---------------------------------------------- | ---------------------------------------------------------------- | +| [Box](/components/layout/box) | You need a custom flex or grid layout, or visual utilities | +| [Stack](/components/layout/stack) | Direct children should flow on the logical block axis | +| [Cluster](/components/layout/cluster) | Direct children should flow on the logical inline axis and wrap | +| [Container](/components/layout/container) | Content needs a maximum inline size and local responsive queries | +| [AspectRatio](/components/layout/aspect-ratio) | Media should fill a locked inline-to-block ratio | ## Box @@ -37,11 +39,11 @@ input `className` or `style` with the generated values. ## Responsive values Properties passed to `Box` and Sprinkles accept either a direct value or an object keyed by -breakpoint. Stack and Cluster accept the same responsive form for the layout props they expose. +breakpoint. Layout utility props exposed by layout components accept the same responsive form. Responsive values resolve against the nearest ancestor size container. Luke UI uses the document -root as the fallback. Add `container-type: inline-size` to a nearer ancestor when descendants should -respond to that element instead. +root as the fallback. Use `Container` when descendants should respond to a nearer content area. +Component-responsive styles always query an ancestor. They do not query the component itself. Portalled content leaves containers around its trigger and resolves against the nearest size container at its portal location, falling back to the root when there is none. @@ -95,6 +97,12 @@ defines its spacing scale and typography styles in source. Cluster wrapping children on the inline axis. + + Constrain content and establish a local size container. + + + Lock media to an inline-to-block ratio. + See the Box example, props, and custom element rendering contract. diff --git a/apps/docs/src/examples/aspect-ratio/basic.tsx b/apps/docs/src/examples/aspect-ratio/basic.tsx new file mode 100644 index 00000000..fa07064d --- /dev/null +++ b/apps/docs/src/examples/aspect-ratio/basic.tsx @@ -0,0 +1,17 @@ +import { AspectRatio } from '@luke-ui/react/aspect-ratio'; +import { Container } from '@luke-ui/react/container'; +import { vars } from '@luke-ui/react/theme'; + +export default () => { + return ( + + +