sheerly 0.0.1 → 0.0.2

package/src/alert.tsx

@@ -1,25 +1,63 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export interface AlertProps extends HTMLAttributes<HTMLDivElement> {
-  'data-variant'?: 'default' | 'destructive' | 'success' | 'info' | 'warning'
-}
+export type AlertProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-variant'?: 'default' | 'destructive' | 'success' | 'info' | 'warning' }
+>
 
-export function Alert({ className, role = 'alert', ...props }: AlertProps) {
-  return <div role={role} className={cn('sheerly-alert', className)} {...props} />
+/**
+ * A callout. The leading icon is embedded in CSS and swaps per `data-variant`.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Alert data-variant="warning">
+ *   <AlertTitle>Heads up</AlertTitle>
+ *   <AlertDescription>Your session expires soon.</AlertDescription>
+ * </Alert>
+ */
+export function Alert<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: AlertProps<T>) {
+  const Tag = as ?? 'div'
+  return (
+    <Tag role="alert" className={cn('sheerly-alert', className)} {...props} />
+  )
 }
 
-export function AlertTitle({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-alert-title', className)} {...props} />
+export type AlertTitleProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function AlertTitle<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: AlertTitleProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-alert-title', className)} {...props} />
 }
 
-export function AlertDescription({
+export type AlertDescriptionProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function AlertDescription<T extends ElementType = 'div'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-alert-description', className)} {...props} />
+}: AlertDescriptionProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-alert-description', className)} {...props} />
 }
 
-export function AlertAction({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-alert-action', className)} {...props} />
+export type AlertActionProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function AlertAction<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: AlertActionProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-alert-action', className)} {...props} />
 }

package/src/avatar.css

@@ -1,6 +1,5 @@
 /* Avatar — circular image with initials fallback */
 .sheerly-avatar {
-  position: relative;
   display: flex;
   flex-shrink: 0;
   overflow: hidden;

package/src/avatar.tsx

@@ -1,12 +1,31 @@
-import type { HTMLAttributes, ImgHTMLAttributes } from 'react'
-import { cn } from './cn'
-
-export interface AvatarProps extends HTMLAttributes<HTMLDivElement> {
-  'data-size'?: 'sm' | 'default' | 'lg' | 'xl'
-}
-
-export function Avatar({ className, ...props }: AvatarProps) {
-  return <div className={cn('sheerly-avatar', className)} {...props} />
+import type { ElementType, ImgHTMLAttributes } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
+
+export type AvatarProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-size'?: 'sm' | 'default' | 'lg' | 'xl' }
+>
+
+/**
+ * A circular avatar. Nest an <AvatarImage> with an <AvatarFallback> for initials.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`, e.g.
+ * `as="a"` for a linkable avatar).
+ *
+ * @example
+ * <Avatar>
+ *   <AvatarImage src="/me.jpg" alt="Ada" />
+ *   <AvatarFallback>AL</AvatarFallback>
+ * </Avatar>
+ */
+export function Avatar<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: AvatarProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-avatar', className)} {...props} />
 }
 
 export interface AvatarImageProps extends ImgHTMLAttributes<HTMLImageElement> {
@@ -17,14 +36,24 @@ export function AvatarImage(props: AvatarImageProps) {
   return <img {...props} />
 }
 
-export type AvatarFallbackProps = HTMLAttributes<HTMLSpanElement>
+export type AvatarFallbackProps<T extends ElementType = 'span'> = PolymorphicProps<T>
 
-export function AvatarFallback({ className, ...props }: AvatarFallbackProps) {
-  return <span className={cn('sheerly-avatar-fallback', className)} {...props} />
+export function AvatarFallback<T extends ElementType = 'span'>({
+  as,
+  className,
+  ...props
+}: AvatarFallbackProps<T>) {
+  const Tag = as ?? 'span'
+  return <Tag className={cn('sheerly-avatar-fallback', className)} {...props} />
 }
 
-export type AvatarGroupProps = HTMLAttributes<HTMLDivElement>
+export type AvatarGroupProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function AvatarGroup({ className, ...props }: AvatarGroupProps) {
-  return <div className={cn('sheerly-avatar-group', className)} {...props} />
+export function AvatarGroup<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: AvatarGroupProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-avatar-group', className)} {...props} />
 }

package/src/badge.tsx

@@ -1,19 +1,37 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
-  'data-variant'?:
-    | 'default'
-    | 'secondary'
-    | 'destructive'
-    | 'outline'
-    | 'ghost'
-    | 'success'
-    | 'warning'
-    | 'error'
-    | 'blue'
-}
+export type BadgeProps<T extends ElementType = 'span'> = PolymorphicProps<
+  T,
+  {
+    'data-variant'?:
+      | 'default'
+      | 'secondary'
+      | 'destructive'
+      | 'outline'
+      | 'ghost'
+      | 'success'
+      | 'warning'
+      | 'error'
+      | 'blue'
+  }
+>
 
-export function Badge({ className, ...props }: BadgeProps) {
-  return <span className={cn('sheerly-badge', className)} {...props} />
+/**
+ * A pill-shaped label. Set `data-variant` for color.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `span`, e.g.
+ * `as="a"` for a linkable badge).
+ *
+ * @example
+ * <Badge data-variant="success">Active</Badge>
+ */
+export function Badge<T extends ElementType = 'span'>({
+  as,
+  className,
+  ...props
+}: BadgeProps<T>) {
+  const Tag = as ?? 'span'
+  return <Tag className={cn('sheerly-badge', className)} {...props} />
 }

package/src/breadcrumb.tsx

@@ -1,6 +1,19 @@
-import type { AnchorHTMLAttributes, HTMLAttributes, OlHTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { AnchorHTMLAttributes, ElementType, HTMLAttributes, OlHTMLAttributes } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
+/**
+ * A path hierarchy of links.
+ *
+ * @example
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem><BreadcrumbPage>Docs</BreadcrumbPage></BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ */
 export function Breadcrumb({ className, ...props }: HTMLAttributes<HTMLElement>) {
   return (
     <nav
@@ -23,9 +36,16 @@ export function BreadcrumbLink({ className, ...props }: AnchorHTMLAttributes<HTM
   return <a className={cn('sheerly-breadcrumb-link', className)} {...props} />
 }
 
-export function BreadcrumbPage({ className, ...props }: HTMLAttributes<HTMLSpanElement>) {
+export type BreadcrumbPageProps<T extends ElementType = 'span'> = PolymorphicProps<T>
+
+export function BreadcrumbPage<T extends ElementType = 'span'>({
+  as,
+  className,
+  ...props
+}: BreadcrumbPageProps<T>) {
+  const Tag = as ?? 'span'
   return (
-    <span
+    <Tag
       role="link"
       aria-disabled="true"
       aria-current="page"
@@ -52,13 +72,17 @@ export function BreadcrumbSeparator({
   )
 }
 
-export function BreadcrumbEllipsis({
+export type BreadcrumbEllipsisProps<T extends ElementType = 'span'> = PolymorphicProps<T>
+
+export function BreadcrumbEllipsis<T extends ElementType = 'span'>({
+  as,
   className,
   children,
   ...props
-}: HTMLAttributes<HTMLSpanElement>) {
+}: BreadcrumbEllipsisProps<T>) {
+  const Tag = as ?? 'span'
   return (
-    <span
+    <Tag
       role="presentation"
       aria-hidden="true"
       aria-label="More"
@@ -66,6 +90,6 @@ export function BreadcrumbEllipsis({
       {...props}
     >
       {children}
-    </span>
+    </Tag>
   )
 }

package/src/button.css

@@ -15,6 +15,7 @@
   outline: none;
   cursor: pointer;
   border: 1px solid transparent;
+  box-sizing: border-box;
   text-decoration: none;
   user-select: none;
 

package/src/button.tsx

@@ -1,30 +1,47 @@
-import type { ButtonHTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  'data-variant'?:
-    | 'default'
-    | 'primary'
-    | 'secondary'
-    | 'tertiary'
-    | 'ghost'
-    | 'muted'
-    | 'destructive'
-    | 'error'
-    | 'outline'
-    | 'link'
-  'data-size'?:
-    | 'xs'
-    | 'sm'
-    | 'default'
-    | 'lg'
-    | 'icon'
-    | 'icon-xs'
-    | 'icon-sm'
-    | 'icon-lg'
-  'data-rounded'?: 'full'
-}
+export type ButtonProps<T extends ElementType = 'button'> = PolymorphicProps<
+  T,
+  {
+    'data-variant'?:
+      | 'default'
+      | 'primary'
+      | 'secondary'
+      | 'tertiary'
+      | 'ghost'
+      | 'muted'
+      | 'destructive'
+      | 'error'
+      | 'outline'
+      | 'link'
+    'data-size'?:
+      | 'xs'
+      | 'sm'
+      | 'default'
+      | 'lg'
+      | 'icon'
+      | 'icon-xs'
+      | 'icon-sm'
+      | 'icon-lg'
+    'data-rounded'?: 'full'
+  }
+>
 
-export function Button({ className, ...props }: ButtonProps) {
-  return <button className={cn('sheerly-button', className)} {...props} />
+/**
+ * A button. Defaults to the primary variant; set `data-variant` / `data-size`
+ * to change it.
+ *
+ * @example
+ * <Button data-variant="secondary">Save</Button>
+ * <Button as="a" role="button" href="/settings">Settings</Button>
+ */
+export function Button<T extends ElementType = 'button'>({
+  as,
+  className,
+  ...props
+}: ButtonProps<T>) {
+  const Tag = as ?? 'button'
+  return <Tag className={cn('sheerly-button', className)} {...props} />
 }

package/src/card.tsx

@@ -1,41 +1,100 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export interface CardProps extends HTMLAttributes<HTMLDivElement> {
-  'data-size'?: 'default' | 'sm'
-}
+export type CardProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-size'?: 'default' | 'sm' }
+>
 
-export function Card({ className, ...props }: CardProps) {
-  return <div className={cn('sheerly-card', className)} {...props} />
+/**
+ * A surface container. Compose with the sub-parts below.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Card as="article">
+ *   <CardHeader>
+ *     <CardTitle>Notifications</CardTitle>
+ *     <CardDescription>You have 3 unread.</CardDescription>
+ *   </CardHeader>
+ *   <CardContent>…</CardContent>
+ * </Card>
+ */
+export function Card<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CardProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-card', className)} {...props} />
 }
 
-export function CardHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-card-header', className)} {...props} />
-}
+export type CardHeaderProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function CardTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
-  return <h3 className={cn('sheerly-card-title', className)} {...props} />
+export function CardHeader<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CardHeaderProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-card-header', className)} {...props} />
 }
 
-export function CardDescription({
+export type CardTitleProps<T extends ElementType = 'h3'> = PolymorphicProps<T>
+
+export function CardTitle<T extends ElementType = 'h3'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLParagraphElement>) {
-  return <p className={cn('sheerly-card-description', className)} {...props} />
+}: CardTitleProps<T>) {
+  const Tag = as ?? 'h3'
+  return <Tag className={cn('sheerly-card-title', className)} {...props} />
 }
 
-export function CardAction({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-card-action', className)} {...props} />
+export type CardDescriptionProps<T extends ElementType = 'p'> = PolymorphicProps<T>
+
+export function CardDescription<T extends ElementType = 'p'>({
+  as,
+  className,
+  ...props
+}: CardDescriptionProps<T>) {
+  const Tag = as ?? 'p'
+  return <Tag className={cn('sheerly-card-description', className)} {...props} />
 }
 
-export function CardContent({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-card-content', className)} {...props} />
+export type CardActionProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function CardAction<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CardActionProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-card-action', className)} {...props} />
 }
 
-export interface CardFooterProps extends HTMLAttributes<HTMLDivElement> {
-  'data-direction'?: 'column'
+export type CardContentProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function CardContent<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CardContentProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-card-content', className)} {...props} />
 }
 
-export function CardFooter({ className, ...props }: CardFooterProps) {
-  return <div className={cn('sheerly-card-footer', className)} {...props} />
+export type CardFooterProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-direction'?: 'column' }
+>
+
+export function CardFooter<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CardFooterProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-card-footer', className)} {...props} />
 }

package/src/carousel.tsx

@@ -1,7 +1,8 @@
-import type { HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export type CarouselProps = HTMLAttributes<HTMLDivElement>
+export type CarouselProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
 /**
  * Pure-CSS carousel. The element itself is the scroll container — put
@@ -14,17 +15,33 @@ export type CarouselProps = HTMLAttributes<HTMLDivElement>
  * component sets no gap on purpose (a fixed basis + gap breaks first/last
  * snapping, so the prev/next buttons wouldn't disable and end dots wouldn't
  * highlight).
+ *
+ * @example
+ * <Carousel>
+ *   <CarouselItem data-name="Slide 1">…</CarouselItem>
+ *   <CarouselItem data-name="Slide 2">…</CarouselItem>
+ * </Carousel>
  */
-export function Carousel({ className, ...props }: CarouselProps) {
-  return <div className={cn('sheerly-carousel', className)} {...props} />
+export function Carousel<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CarouselProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-carousel', className)} {...props} />
 }
 
-export interface CarouselItemProps extends HTMLAttributes<HTMLDivElement> {
-  /** Accessible name for this slide's generated scroll marker (WCAG). */
-  'data-name'?: string
-}
+export type CarouselItemProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { /** Accessible name for this slide's generated scroll marker (WCAG). */ 'data-name'?: string }
+>
 
 /** A slide. Defaults to `width: 100%` (one per page); override via `style`/`className`. */
-export function CarouselItem({ className, ...props }: CarouselItemProps) {
-  return <div className={cn('sheerly-carousel-item', className)} {...props} />
+export function CarouselItem<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: CarouselItemProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-carousel-item', className)} {...props} />
 }

package/src/checkbox.tsx

@@ -1,8 +1,14 @@
 import type { InputHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
 
+/**
+ * A checkbox `<input>`. Pair with a <Label> for a clickable target.
+ *
+ * @example
+ * <Checkbox id="terms" defaultChecked />
+ */
 export function Checkbox({ className, ...props }: CheckboxProps) {
   return (
     <input type="checkbox" className={cn('sheerly-checkbox', className)} {...props} />

package/src/dialog.tsx

@@ -1,39 +1,78 @@
-import type { ButtonHTMLAttributes, DialogHTMLAttributes, HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ButtonHTMLAttributes, DialogHTMLAttributes, ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
 /**
  * Native <dialog>. Open via invoker command (`command="show-modal"`) or
  * `.showModal()`. Add `closedby="any"` for light-dismiss.
+ *
+ * @example
+ * <button commandfor="d" command="show-modal">Open</button>
+ * <Dialog id="d" closedby="any">
+ *   <DialogHeader><DialogTitle>Confirm</DialogTitle></DialogHeader>
+ *   <DialogFooter><DialogClose command="close" commandfor="d">Cancel</DialogClose></DialogFooter>
+ * </Dialog>
  */
 export function Dialog({ className, ...props }: DialogHTMLAttributes<HTMLDialogElement>) {
   return <dialog className={cn('sheerly-dialog', className)} {...props} />
 }
 
-export function DialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-dialog-header', className)} {...props} />
-}
+export type DialogHeaderProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function DialogTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
-  return <h3 className={cn('sheerly-dialog-title', className)} {...props} />
+export function DialogHeader<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: DialogHeaderProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-dialog-header', className)} {...props} />
 }
 
-export function DialogDescription({
+export type DialogTitleProps<T extends ElementType = 'h3'> = PolymorphicProps<T>
+
+export function DialogTitle<T extends ElementType = 'h3'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLParagraphElement>) {
-  return <p className={cn('sheerly-dialog-description', className)} {...props} />
+}: DialogTitleProps<T>) {
+  const Tag = as ?? 'h3'
+  return <Tag className={cn('sheerly-dialog-title', className)} {...props} />
 }
 
-export function DialogBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-dialog-body', className)} {...props} />
+export type DialogDescriptionProps<T extends ElementType = 'p'> = PolymorphicProps<T>
+
+export function DialogDescription<T extends ElementType = 'p'>({
+  as,
+  className,
+  ...props
+}: DialogDescriptionProps<T>) {
+  const Tag = as ?? 'p'
+  return <Tag className={cn('sheerly-dialog-description', className)} {...props} />
 }
 
-export interface DialogFooterProps extends HTMLAttributes<HTMLDivElement> {
-  'data-direction'?: 'column'
+export type DialogBodyProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function DialogBody<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: DialogBodyProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-dialog-body', className)} {...props} />
 }
 
-export function DialogFooter({ className, ...props }: DialogFooterProps) {
-  return <div className={cn('sheerly-dialog-footer', className)} {...props} />
+export type DialogFooterProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-direction'?: 'column' }
+>
+
+export function DialogFooter<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: DialogFooterProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-dialog-footer', className)} {...props} />
 }
 
 export function DialogClose({