@sakura-ui/sakura-ui 0.4.1 → 0.5.0

package/README.md

@@ -25,6 +25,13 @@ $ pnpm add @sakura-ui/core @sakura-ui/forms @sakura-ui/tailwind-theme-plugin @sa
 $ pnpm add @sakura-ui/core@0.3.1 @sakura-ui/forms@0.2.2 @sakura-ui/tailwind-theme-plugin@0.2.2 @sakura-ui/markdown@0.0.17
 ```
 
+### For the Card API before 0.5.0
+`Card` and `LinkCard` changed shape in `@sakura-ui/core` 0.5.0. See
+[Card and LinkCard](#card-and-linkcard) for what to change; to stay on the old API for now:
+```
+$ pnpm add @sakura-ui/core@0.4.1 @sakura-ui/markdown@0.2.2
+```
+
 ## Configuration
 tailwind.config.js
 ```ts
@@ -103,6 +110,40 @@ export default App
 - Link
 - Card
 - LinkCard
+
+### Card and LinkCard
+`CardHeader` needs an `as` property. There is no default: the right level depends on the
+document outline around the card, and a wrong guess breaks heading navigation. Use `p` for
+lists of many cards, where headings would only add noise.
+
+```tsx
+<Card>
+  <CardHeader as="h3">Title</CardHeader>
+  <CardBody>Body</CardBody>
+</Card>
+```
+
+`LinkCard` puts the link in the title, and the link covers the whole card. Because of that a
+link card cannot contain another link, a button or a form control.
+
+```tsx
+<LinkCard>
+  <LinkCardHeader as="h3" href="/readme">Title</LinkCardHeader>
+  <CardBody>Body</CardBody>
+  <LinkCardFooter>June 27th, 2026</LinkCardFooter>
+</LinkCard>
+```
+
+`Card` renders a `div` and carries no ARIA of its own, so nothing can dangle or collide. A
+`div` maps to the generic role, which cannot take an accessible name. When a card really is a
+self-contained composition, name it yourself:
+
+```tsx
+<Card as="article" aria-labelledby="card-title">
+  <CardHeader as="h3" id="card-title">Title</CardHeader>
+  <CardBody>Body</CardBody>
+</Card>
+```
 - Ol
 - Ul
 - Table
@@ -128,9 +169,55 @@ export default App
 - LabelControl
 - FieldsetControl
 
+Every form control takes its accessible name from the label it is associated with, so wrap it in `LabelControl` — or `FieldsetControl` for a group of radios or checkboxes. A control rendered without a label has no name for assistive technology.
+
+```tsx
+<LabelControl labelText="添付書類" isRequired>
+  <FileInput />
+</LabelControl>
+```
+
+If a visible label is not an option, pass `aria-label` yourself; it is forwarded to the underlying element.
+
 ## Markdwon extension
 - Markdown
 
+## Accessible names
+
+A note for anyone working on these components, rather than for people using them.
+
+Whether an element can be named at all is decided by its role, not by the attribute
+you write. Every ARIA role declares where its name may come from:
+
+| Name from | Meaning | Roles |
+|---|---|---|
+| author, contents | `aria-label`, `aria-labelledby`, **or the text inside** | `button`, `link`, `heading`, `cell`, `option`, `tab`, `menuitem` |
+| author | `aria-label`, `aria-labelledby` or `title` **only** | `article`, `region`, `dialog`, `img`, `table`, `form` |
+| prohibited | cannot be named; the attribute is ignored | `generic` (a bare `<div>` or `<span>`), `paragraph` |
+
+Two consequences catch people out.
+
+**A `<div>` cannot be given a name.** It maps to `generic`, where naming is prohibited,
+so `<div aria-label="Card">` does nothing at all. Reaching for a name means reaching for
+a different element, which is why dropping `aria-labelledby` from `Card` and dropping its
+`<article>` were the same decision.
+
+**An `<article>` does not take its name from a heading inside it.** It is named by the
+author only, so `<article><h3>Title</h3></article>` has no accessible name. A `<button>`
+or an `<a>` would be named "Title" here, because those are named from their contents.
+Mixing the two up is what made `LinkCard` produce a link with no name: an `<a>` wrapping
+an `<article>` never reached the title, because Chrome does not descend into a role that
+is named by its author.
+
+So, in practice:
+
+- Leave it a `<div>` and give it no name. A list and the headings inside it already tell
+  the reader where they are.
+- Use `<section>` only with a name. A `<section>` becomes a `region` **because** it has one;
+  without a name it is no different from a `<div>`.
+- Use `<article>` only for something that stands on its own, and name it when you do.
+  Naming it is recommended by the APG so that readers can tell one article from the next.
+
 ## Development
 
 ### Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakura-ui/sakura-ui",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "keywords": [],
   "author": "glassonion1",
   "homepage": "https://github.com/glassonion1/sakura-ui",
@@ -19,9 +19,9 @@
     "pnpm": ">=9.15.1"
   },
   "dependencies": {
-    "@sakura-ui/core": "0.4.1",
+    "@sakura-ui/forms": "0.4.2",
+    "@sakura-ui/core": "0.5.0",
     "@sakura-ui/helper": "0.0.9",
-    "@sakura-ui/forms": "0.4.1",
     "@sakura-ui/tailwind-theme-plugin": "0.4.1"
   },
   "peerDependencies": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakura-ui/core",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "",
   "keywords": [
     "react",

package/packages/core/src/components/Card.tsx

@@ -1,21 +1,16 @@
 import React from 'react'
 import { cx } from '@sakura-ui/helper'
 
-interface IdContextType {
-  id: string
-}
-
-const IdContext = React.createContext<IdContextType>({ id: '' })
-
 export namespace Card {
-  export interface Props extends React.ComponentPropsWithoutRef<'article'> {}
+  export interface Props<T extends React.ElementType> {
+    as?: T
+  }
 }
 
-export const Card = (props: Card.Props) => {
-  const { className, children, ...restProps } = props
-
-  const id = React.useId()
-  const ctx: IdContextType = { id: id }
+export const Card = <T extends React.ElementType = 'div'>(
+  props: Card.Props<T> & Omit<React.ComponentProps<T>, keyof Card.Props<T>>
+) => {
+  const { as: Component = 'div', className, children, ...restProps } = props
 
   const style = `
     border
@@ -27,20 +22,17 @@ export const Card = (props: Card.Props) => {
     overflow-hidden
   `
 
+  // A div cannot carry an accessible name, so no ARIA is set here. See the
+  // Accessible names section of the README before adding any.
   return (
-    <IdContext value={ctx}>
-      <article
-        aria-labelledby={ctx.id}
-        aria-describedby={`${ctx.id}-desc`}
-        className={cx(style, className)}
-        {...restProps}
-      >
-        {children}
-      </article>
-    </IdContext>
+    <Component className={cx(style, className)} {...restProps}>
+      {children}
+    </Component>
   )
 }
 
+Card.displayName = 'Card'
+
 export namespace CardImg {
   export interface Props extends React.ComponentPropsWithoutRef<'img'> {}
 }
@@ -57,16 +49,37 @@ export const CardImg = (props: CardImg.Props) => {
   return <img className={cx(style, className)} {...restProps} />
 }
 
+CardImg.displayName = 'CardImg'
+
+export type CardHeaderAs = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p'
+
 export namespace CardHeader {
-  export interface Props extends React.ComponentPropsWithoutRef<'div'> {}
+  export interface Props extends React.ComponentPropsWithoutRef<'h3'> {
+    /**
+     * The element to render the title as. Required on purpose: the right level
+     * depends on the surrounding document outline, so the library must not pick
+     * one. Use 'p' for lists of many cards, where headings would add noise.
+     */
+    as: CardHeaderAs
+  }
 }
 
 export const CardHeader = (props: CardHeader.Props) => {
-  const { className, children, ...restProps } = props
-
-  const ctx = React.useContext(IdContext)
-
+  const { as: Component, className, children, ...restProps } = props
+
+  if (!Component) {
+    // Without this, React reports an invalid element type and suggests a missing
+    // export, which says nothing about the property that was actually left out.
+    throw new Error(
+      'CardHeader: the "as" property is required. Pass the heading level that ' +
+        'fits the outline around the card, or "p" for lists of many cards.'
+    )
+  }
+
+  // Reset the browser defaults of the heading and paragraph elements so that the
+  // rendered element does not change how the card looks.
   const style = `
+    m-0
     text-base
     leading-[2rem]
     font-medium
@@ -77,12 +90,14 @@ export const CardHeader = (props: CardHeader.Props) => {
   `
 
   return (
-    <div id={ctx.id} className={cx(style, className)} {...restProps}>
+    <Component className={cx(style, className)} {...restProps}>
       {children}
-    </div>
+    </Component>
   )
 }
 
+CardHeader.displayName = 'CardHeader'
+
 export namespace CardBody {
   export interface Props extends React.ComponentPropsWithoutRef<'div'> {}
 }
@@ -90,8 +105,6 @@ export namespace CardBody {
 export const CardBody = (props: CardBody.Props) => {
   const { className, children, ...restProps } = props
 
-  const ctx = React.useContext(IdContext)
-
   const style = `
     text-base-sm
     leading-[1.85rem]
@@ -101,13 +114,17 @@ export const CardBody = (props: CardBody.Props) => {
     px-6
   `
 
+  // No generated id here. Callers that want the body to describe the card pass
+  // their own id and point aria-describedby at it.
   return (
-    <div id={`${ctx.id}-desc`} className={cx(style, className)} {...restProps}>
+    <div className={cx(style, className)} {...restProps}>
       {children}
     </div>
   )
 }
 
+CardBody.displayName = 'CardBody'
+
 export namespace CardFooter {
   export interface Props extends React.ComponentPropsWithoutRef<'div'> {}
 }
@@ -135,3 +152,5 @@ export const CardFooter = (props: CardFooter.Props) => {
     </div>
   )
 }
+
+CardFooter.displayName = 'CardFooter'

package/packages/core/src/components/Faq.tsx

@@ -18,18 +18,12 @@ export const Faq = (props: Faq.Props) => {
     flex-col
     gap-8
   `
+  // No schema.org FAQPage markup here. Google discontinued the FAQ rich result
+  // in May 2026, so it is not implemented.
   return (
-    <article itemScope itemType="https://schema.org/FAQPage">
-      <dl
-        className={cx(style, className)}
-        itemScope
-        itemProp="mainEntity"
-        itemType="https://schema.org/Question"
-        {...restProps}
-      >
-        {children}
-      </dl>
-    </article>
+    <dl className={cx(style, className)} {...restProps}>
+      {children}
+    </dl>
   )
 }
 
@@ -47,11 +41,7 @@ export const Question = (props: Question.Props) => {
     mt-8
   `
   return (
-    <dt
-      className={cx(style, headingStyle, className)}
-      itemProp="name"
-      {...restProps}
-    >
+    <dt className={cx(style, headingStyle, className)} {...restProps}>
       <span aria-hidden="true">Q</span>
       <span>{children}</span>
     </dt>
@@ -72,17 +62,11 @@ export const Answer = (props: Answer.Props) => {
     gap-8
   `
   return (
-    <dd
-      className={cx(style, className)}
-      itemScope
-      itemProp="acceptedAnswer"
-      itemType="https://schema.org/Answer"
-      {...restProps}
-    >
+    <dd className={cx(style, className)} {...restProps}>
       <span className={cx(headingStyle, '!leading-none')} aria-hidden="true">
         A
       </span>
-      <span itemProp="text">{children}</span>
+      <span>{children}</span>
     </dd>
   )
 }

package/packages/core/src/components/LinkCard.tsx

@@ -1,98 +1,145 @@
 import React from 'react'
-import { cx, Style } from '@sakura-ui/helper'
-import { Card, CardFooter, CardHeader } from './Card'
+import { cx } from '@sakura-ui/helper'
+import { Card, CardFooter, CardHeader, type CardHeaderAs } from './Card'
 import { Icon } from './Icon'
 
 export namespace LinkCard {
-  export interface Props<T extends React.ElementType>
-    extends React.ComponentProps<'article'> {
-    href: string
-    target?: string
-    linkAs?: T
-  }
+  export interface Props<T extends React.ElementType> extends Card.Props<T> {}
 }
 
-export const LinkCard = <T extends React.ElementType = 'a'>(
-  props: LinkCard.Props<T>
+/**
+ * A Card whose title carries the link. The link stretches over the whole card
+ * through a ::after overlay, so the card cannot contain another link, a button
+ * or a form control.
+ */
+export const LinkCard = <T extends React.ElementType = 'div'>(
+  props: LinkCard.Props<T> & Omit<React.ComponentProps<T>, keyof LinkCard.Props<T>>
 ) => {
-  const {
-    href,
-    target,
-    linkAs: Component = 'a',
-    className,
-    children,
-    ...rest
-  } = props
+  const { className, children, ...restProps } = props
 
-  const styleLink = `
-    grid
-    outline-offset-4
-    rounded-2xl
-    sm:rounded-3xl
-    w-full h-full
-    ${Style.focusCard}
+  // z-0 establishes a stacking context so that the overlay of the title can be
+  // raised above the rest of the card. CardFooter is sticky, which makes it a
+  // positioned element that would otherwise paint over the overlay and swallow
+  // the clicks aimed at the bottom of the card.
+  const stylePosition = `
+    relative
+    z-0
     group
   `
 
   const styleHover = `
-    group-hover:outline
-    group-hover:outline-blue-900
-    group-hover:outline-4
-    group-hover:outline-offset-[-1px]
+    hover:outline
+    hover:outline-2
+    hover:outline-black
+    hover:bg-solid-gray-50
   `
 
+  // The focus ring goes on the card itself, not on the <a>, so that it surrounds
+  // the whole card. The card sets overflow-hidden, which would cut off a ring
+  // drawn on the ::after overlay inside it. An element never clips its own
+  // outline, so the ring survives here.
+  const styleFocus = `
+    has-[a:focus-visible]:outline
+    has-[a:focus-visible]:outline-4
+    has-[a:focus-visible]:outline-black
+    has-[a:focus-visible]:outline-offset-[calc(2/16*1rem)]
+    has-[a:focus-visible]:ring-[calc(2/16*1rem)]
+    has-[a:focus-visible]:ring-yellow-300
+  `
+
+  // TypeScript cannot carry the generic through to Card, which is polymorphic in
+  // the same way. The public signature above stays exact; only this hand-off is
+  // widened.
+  const Root = Card as React.ElementType
+
   return (
-    <Component className={cx(styleLink)} href={href} target={target}>
-      <Card className={cx(styleHover, className)} {...rest}>
-        {children}
-      </Card>
-    </Component>
+    <Root
+      className={cx(stylePosition, styleHover, styleFocus, className)}
+      {...restProps}
+    >
+      {children}
+    </Root>
   )
 }
 
+LinkCard.displayName = 'LinkCard'
+
 export namespace LinkCardHeader {
-  export interface Props extends React.ComponentProps<'div'> {
-    target?: string
+  export interface Props<T extends React.ElementType> {
+    /** The element to render the title as. See CardHeader. */
+    as: CardHeaderAs
+    /** The component to render the link as. Defaults to an anchor element. */
+    linkAs?: T
   }
 }
 
-export const LinkCardHeader = ({
-  target,
-  className,
-  children
-}: LinkCardHeader.Props) => {
+/**
+ * The title of a LinkCard, holding the link that covers the whole card.
+ *
+ * `className` styles the title element; every other prop (href, target, and
+ * whatever the component passed to `linkAs` accepts) goes to the link.
+ */
+export const LinkCardHeader = <T extends React.ElementType = 'a'>(
+  props: LinkCardHeader.Props<T> &
+    Omit<React.ComponentProps<T>, keyof LinkCardHeader.Props<T>>
+) => {
+  const {
+    as,
+    linkAs: Component = 'a',
+    className,
+    children,
+    ...restProps
+  } = props
+
+  if (!as) {
+    throw new Error(
+      'LinkCardHeader: the "as" property is required. Pass the heading level ' +
+        'that fits the outline around the card, or "p" for lists of many cards.'
+    )
+  }
+
   const styleHeading = `
     decoration-blue-900
     underline
     underline-offset-[calc(3/16*1rem)]
-  `
-  const styleHover = `
+   
     group-hover:text-blue-900
     group-hover:decoration-[calc(3/16*1rem)]
   `
 
+  // The ::after overlay makes the whole card clickable. It carries no visual of
+  // its own; the focus ring lives on the LinkCard element.
+  const styleOverlay = `
+    after:content-['']
+    after:absolute
+    after:inset-0
+    after:z-10
+    focus-visible:outline-none
+  `
+
   return (
-    <CardHeader className={cx(className, styleHeading, styleHover)}>
-      <span>
+    <CardHeader as={as} className={cx(className, styleHeading)}>
+      <Component className={styleOverlay} {...restProps}>
         {children}
-        {target === '_blank' && (
-          <Icon opticalSize={16} className="ml-1">
+        {restProps.target === '_blank' && (
+          <Icon opticalSize={16} className="ml-1" altText="新しいタブで開きます">
             open_in_new
           </Icon>
         )}
-      </span>
+      </Component>
     </CardHeader>
   )
 }
 
+LinkCardHeader.displayName = 'LinkCardHeader'
+
 export namespace LinkCardFooter {
-  export interface Props extends React.ComponentProps<'div'> {}
+  export interface Props extends React.ComponentPropsWithoutRef<'div'> {}
 }
 
-export const LinkCardFooter = ({
-  className,
-  children
-}: LinkCardFooter.Props) => {
+export const LinkCardFooter = (props: LinkCardFooter.Props) => {
+  const { className, children, ...restProps } = props
+
   const style = `
     flex
     justify-between
@@ -116,7 +163,7 @@ export const LinkCardFooter = ({
   `
 
   return (
-    <CardFooter className={cx(className, style)}>
+    <CardFooter className={cx(style, className)} {...restProps}>
       <span>{children}</span>
       <span className={cx(styleIcon, styleIconHover)}>
         <Icon opticalSize={16}>arrow_forward</Icon>
@@ -124,3 +171,5 @@ export const LinkCardFooter = ({
     </CardFooter>
   )
 }
+
+LinkCardFooter.displayName = 'LinkCardFooter'

package/packages/core/src/components/index.ts

@@ -1,6 +1,7 @@
 export { Button } from './Button'
 export { MenuButton } from './MenuButton'
 export { Card, CardImg, CardHeader, CardBody, CardFooter } from './Card'
+export type { CardHeaderAs } from './Card'
 export { LinkCard, LinkCardHeader, LinkCardFooter } from './LinkCard'
 export { Code } from './Code'
 export { Faq, Question, Answer } from './Faq'

package/packages/core/src/index.ts

@@ -38,3 +38,5 @@ export {
   PopoverMenu,
   PopoverMenuItem
 } from './components'
+
+export type { CardHeaderAs } from './components'