Skip to content

Commit

Permalink
Rename Library.{Pattern, Example} => Library.{SectionL2, SectionL3}
Browse files Browse the repository at this point in the history 
The hierarchical relationship between `Library.{Section, Pattern, Example}` was
unclear and the `Pattern` and `Example` components had an unclear purpose since
they were used as sections with different kinds of content. Rename these
components to make the structure clearer: `Page` -> `Section` -> `SectionL2` ->
`SectionL3` where `SectionL{N}` is effectively an alias for `<Section
level={N}>`. In the process the meaning of the `level` prop has been adjusted
to match the logical section level.

In the process also correct the usage of the `<main>` element to refer to just
the main content of the page (ie. excluding navigation) instead of the whole
page.
  • Loading branch information
@robertknight
robertknight committed Dec 3, 2024
1 parent f7da9bf commit 04481a5
Show file tree
Hide file tree
Showing 37 changed files with 853 additions and 841 deletions.
42 changes: 27 additions & 15 deletions src/pattern-library/components/Library.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ export type LibraryPageProps = {
*/
function Page({ children, intro, title }: LibraryPageProps) {
return (
<section className="styled-text text-stone-600">
<main className="styled-text text-stone-600">
<div className="px-8 py-4">
<h1 className="text-3xl text-slate-600 font-bold" id="page-header">
{title}
Expand All @@ -43,7 +43,7 @@ function Page({ children, intro, title }: LibraryPageProps) {
)}
{children}
</div>
</section>
</main>
);
}

Expand Down Expand Up @@ -95,7 +95,7 @@ export type LibrarySectionProps = LibraryElementAttributes & {
};

// Keep track of <Section> nested depth
const SectionDepthContext = createContext<number>(1);
const SectionDepthContext = createContext<number>(0);

/**
* Render a primary section of a page. Each component documented on a pattern-
Expand All @@ -116,13 +116,17 @@ function Section({
<section
data-depth={depth}
className={classnames('leading-relaxed', {
'mt-8 mb-16': depth <= 2,
'mt-8 mb-8': depth === 3,
'mt-6 mb-8': depth >= 4,
'mt-8 mb-16': depth <= 1,
'mt-8 mb-8': depth === 2,
'mt-6 mb-8': depth >= 3,
})}
{...htmlAttributes}
>
{title && <Heading level={depth}>{title}</Heading>}
{title && (
// Heading level is one larger than section level because heading
// level 1 is reserved for the main heading of the page.
<Heading level={depth + 1}>{title}</Heading>
)}
{intro && (
<div className="text-base space-y-3 leading-relaxed">{intro}</div>
)}
Expand All @@ -132,23 +136,27 @@ function Section({
);
}

export type LibraryPatternProps = LibraryElementAttributes & {
export type LibrarySectionL2Props = LibraryElementAttributes & {
children?: ComponentChildren;
title?: string;
};

/**
* Render a second-level section. e.g. Usage, Props, Status
*/
function Pattern({ children, title, ...htmlAttributes }: LibraryPatternProps) {
function SectionL2({
children,
title,
...htmlAttributes
}: LibrarySectionL2Props) {
return (
<Section level={3} title={title} {...htmlAttributes}>
<Section level={2} title={title} {...htmlAttributes}>
{children}
</Section>
);
}

export type LibraryExampleProps = LibraryElementAttributes & {
export type LibrarySectionL3Props = LibraryElementAttributes & {
children?: ComponentChildren;
title?: string;
};
Expand All @@ -157,9 +165,13 @@ export type LibraryExampleProps = LibraryElementAttributes & {
* Render content in a third-level section, e.g. documentation
* about a specific prop or examples of usage.
*/
function Example({ children, title, ...htmlAttributes }: LibraryExampleProps) {
function SectionL3({
children,
title,
...htmlAttributes
}: LibrarySectionL3Props) {
return (
<Section level={4} title={title} {...htmlAttributes}>
<Section level={3} title={title} {...htmlAttributes}>
{children}
</Section>
);
Expand Down Expand Up @@ -633,13 +645,13 @@ export default {
ChangelogItem,
Code,
Demo,
Example,
Info,
InfoItem,
Link,
Page,
Pattern,
Section,
SectionL2,
SectionL3,
StatusChip,
Usage,
};
4 changes: 2 additions & 2 deletions src/pattern-library/components/PlaygroundApp.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ export default function PlaygroundApp({
return (
<Router base={baseURL}>
<div className="w-full bg-stone-200">
<main className="max-w-[1300px] mx-auto">
<div className="max-w-[1300px] mx-auto">
<div className="md:grid md:grid-cols-[2fr_5fr]">
<div className="md:h-screen md:sticky md:top-0 border-l border-stone-400 bg-stone-100">
<ScrollContainer borderless>
Expand Down Expand Up @@ -241,7 +241,7 @@ export default function PlaygroundApp({
</Switch>
</div>
</div>
</main>
</div>
</div>
</Router>
);
Expand Down
20 changes: 10 additions & 10 deletions src/pattern-library/components/patterns/ColorsPage.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,37 +70,37 @@ const focusExamples = (
export default function ColorsPage() {
return (
<Library.Page title="Colors">
<Library.Pattern title="Brand red">
<Library.SectionL2 title="Brand red">
<div className="my-4 flex flex-row flex-wrap gap-4">
{brandExamples}
</div>
</Library.Pattern>
</Library.SectionL2>

<Library.Pattern title="Greys">
<Library.SectionL2 title="Greys">
<div className="my-4 flex flex-row flex-wrap gap-4">{greyExamples}</div>
</Library.Pattern>
</Library.SectionL2>

<Library.Pattern title="Slates">
<Library.SectionL2 title="Slates">
<p>
These slightly blue greys may be used sparingly to help with
differentiation and clarity within interfaces.
</p>
<div className="my-4 flex flex-row flex-wrap gap-4">
{slateExamples}
</div>
</Library.Pattern>
</Library.SectionL2>

<Library.Pattern title="State indicators">
<Library.SectionL2 title="State indicators">
<div className="my-4 flex flex-row flex-wrap gap-4">
{stateExamples}
</div>
</Library.Pattern>
</Library.SectionL2>

<Library.Pattern title="Focus indicators">
<Library.SectionL2 title="Focus indicators">
<div className="my-4 flex flex-row flex-wrap gap-4">
{focusExamples}
</div>
</Library.Pattern>
</Library.SectionL2>
</Library.Page>
);
}
16 changes: 8 additions & 8 deletions src/pattern-library/components/patterns/GettingStartedPage.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ export default function GettingStartedPage() {
}
>
<Library.Section>
<Library.Pattern title="Installation">
<Library.SectionL2 title="Installation">
<p>
Your application needs to install{' '}
<Link href="https://tailwindcss.com/" underline="always">
Expand All @@ -27,9 +27,9 @@ export default function GettingStartedPage() {
<Library.Code
content={`$ yarn add tailwindcss @hypothesis/frontend-shared`}
/>
</Library.Pattern>
<Library.Pattern title="Configuration">
<Library.Example title="Configure tailwindcss">
</Library.SectionL2>
<Library.SectionL2 title="Configuration">
<Library.SectionL3 title="Configure tailwindcss">
<p>Configure your {"project's"} tailwind configuration object:</p>
<ul>
<li>Use this {"package's"} tailwind preset</li>
Expand All @@ -51,11 +51,11 @@ export default {
],
// ...`}
/>
</Library.Example>
</Library.Pattern>
<Library.Pattern title="Usage">
</Library.SectionL3>
</Library.SectionL2>
<Library.SectionL2 title="Usage">
<Library.Usage componentName="Card, Link" />
</Library.Pattern>
</Library.SectionL2>
</Library.Section>
</Library.Page>
);
Expand Down
48 changes: 24 additions & 24 deletions src/pattern-library/components/patterns/UsingComponentsPage.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,14 @@ export default function UsingComponentsPage() {
All presentational components provide this API unless documented
otherwise.
</p>
<Library.Example title="children">
<Library.SectionL3 title="children">
<Library.Info>
<Library.InfoItem label="type">
<code>preact.ComponentChildren</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
<Library.Example title="classes">
</Library.SectionL3>
<Library.SectionL3 title="classes">
<Library.Info>
<Library.InfoItem label="description">
CSS class(es) that will be appended to the CSS classes applied
Expand All @@ -54,8 +54,8 @@ export default function UsingComponentsPage() {
<code>string</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
<Library.Example title="elementRef">
</Library.SectionL3>
<Library.SectionL3 title="elementRef">
<Library.Info>
<Library.InfoItem label="description">
A <code>Ref</code> applied to the {"component's"} outermost or
Expand All @@ -65,8 +65,8 @@ export default function UsingComponentsPage() {
<code>{'preact.Ref<HTMLElement | undefined>'}</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
<Library.Example title="...htmlAttributes">
</Library.SectionL3>
<Library.SectionL3 title="...htmlAttributes">
<Library.Info>
<Library.InfoItem label="description">
Presentational components accept HTML attributes applicable to
Expand All @@ -85,7 +85,7 @@ export default function UsingComponentsPage() {
</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>
</Library.Section>

<Library.Section
Expand All @@ -108,7 +108,7 @@ export default function UsingComponentsPage() {
that details how to use these props to customize components.
</p>

<Library.Example title="variant">
<Library.SectionL3 title="variant">
<Library.Info>
<Library.InfoItem label="description">
Many presentational components have multiple variants. Variants{' '}
Expand All @@ -132,9 +132,9 @@ export default function UsingComponentsPage() {
/>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>

<Library.Example title="size">
<Library.SectionL3 title="size">
<Library.Info>
<Library.InfoItem label="description">
Many, but not all, presentational components provide multiple
Expand All @@ -158,9 +158,9 @@ export default function UsingComponentsPage() {
/>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>

<Library.Example title="unstyled">
<Library.SectionL3 title="unstyled">
<Library.Info>
<Library.InfoItem label="description">
Set this to disable all styling. This is a {'"master switch"'}{' '}
Expand All @@ -183,7 +183,7 @@ export default function UsingComponentsPage() {
/>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>
</Library.Section>
</Library.Section>

Expand All @@ -207,7 +207,7 @@ export default function UsingComponentsPage() {
</p>

<Library.Section id="composite-components-api" title="API">
<Library.Example title="children">
<Library.SectionL3 title="children">
<Library.Info>
<Library.InfoItem label="description">
Some, but not all, composite components accept{' '}
Expand All @@ -217,9 +217,9 @@ export default function UsingComponentsPage() {
<code>preact.ComponentChildren</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>

<Library.Example title="elementRef">
<Library.SectionL3 title="elementRef">
<Library.Info>
<Library.InfoItem label="description">
A <code>Ref</code> applied to the {"component's"} outermost or
Expand All @@ -229,9 +229,9 @@ export default function UsingComponentsPage() {
<code>{'preact.Ref<HTMLElement | undefined>'}</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>

<Library.Example title="...htmlAttributes">
<Library.SectionL3 title="...htmlAttributes">
<Library.Info>
<Library.InfoItem label="description">
Some, but not all, composite components accept HTML attributes
Expand All @@ -250,7 +250,7 @@ export default function UsingComponentsPage() {
</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>
</Library.Section>
</Library.Section>

Expand All @@ -268,7 +268,7 @@ export default function UsingComponentsPage() {
</Library.Link>
</p>
<Library.Section title="API" id="transition-components-api">
<Library.Example title="direction">
<Library.SectionL3 title="direction">
<Library.Info>
<Library.InfoItem label="description">
Sets the current direction of the component transition.
Expand All @@ -280,9 +280,9 @@ export default function UsingComponentsPage() {
<code>{"'in'"}</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>

<Library.Example title="onTransitionEnd">
<Library.SectionL3 title="onTransitionEnd">
<Library.Info>
<Library.InfoItem label="description">
Callback invoked when the {"component's"} transition has
Expand All @@ -292,7 +292,7 @@ export default function UsingComponentsPage() {
<code>{`(direction: 'in' | 'out') => void`}</code>
</Library.InfoItem>
</Library.Info>
</Library.Example>
</Library.SectionL3>
</Library.Section>
</Library.Section>

Expand Down
Loading

0 comments on commit 04481a5

Please sign in to comment.