sheerly 0.0.1 → 0.0.3

package/src/accordion.tsx

@@ -1,15 +1,29 @@
-import type { DetailsHTMLAttributes, HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { DetailsHTMLAttributes, ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
 export type AccordionProps = DetailsHTMLAttributes<HTMLDetailsElement>
 
-/** Native <details>. Set the same `name` on siblings for exclusive open. */
+/**
+ * Native <details>. Set the same `name` on siblings for exclusive open.
+ *
+ * @example
+ * <Accordion name="faq">
+ *   <summary>Is it accessible?</summary>
+ *   <AccordionContent>Yes.</AccordionContent>
+ * </Accordion>
+ */
 export function Accordion({ className, ...props }: AccordionProps) {
   return <details className={cn('sheerly-accordion', className)} {...props} />
 }
 
-export type AccordionContentProps = HTMLAttributes<HTMLDivElement>
+export type AccordionContentProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function AccordionContent({ className, ...props }: AccordionContentProps) {
-  return <div className={cn('sheerly-accordion-content', className)} {...props} />
+export function AccordionContent<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: AccordionContentProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-accordion-content', className)} {...props} />
 }

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,9 +1,31 @@
-import type { AnchorHTMLAttributes, HTMLAttributes, OlHTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export function Breadcrumb({ className, ...props }: HTMLAttributes<HTMLElement>) {
+export type BreadcrumbProps<T extends ElementType = 'nav'> = PolymorphicProps<T>
+
+/**
+ * A path hierarchy of links.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `nav`).
+ *
+ * @example
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem><BreadcrumbPage>Docs</BreadcrumbPage></BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ */
+export function Breadcrumb<T extends ElementType = 'nav'>({
+  as,
+  className,
+  ...props
+}: BreadcrumbProps<T>) {
+  const Tag = as ?? 'nav'
   return (
-    <nav
+    <Tag
       aria-label="breadcrumb"
       className={cn('sheerly-breadcrumb', className)}
       {...props}
@@ -11,21 +33,62 @@ export function Breadcrumb({ className, ...props }: HTMLAttributes<HTMLElement>)
   )
 }
 
-export function BreadcrumbList({ className, ...props }: OlHTMLAttributes<HTMLOListElement>) {
-  return <ol className={cn('sheerly-breadcrumb-list', className)} {...props} />
+export type BreadcrumbListProps<T extends ElementType = 'ol'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `ol`).
+ */
+export function BreadcrumbList<T extends ElementType = 'ol'>({
+  as,
+  className,
+  ...props
+}: BreadcrumbListProps<T>) {
+  const Tag = as ?? 'ol'
+  return <Tag className={cn('sheerly-breadcrumb-list', className)} {...props} />
 }
 
-export function BreadcrumbItem({ className, ...props }: HTMLAttributes<HTMLLIElement>) {
-  return <li className={cn('sheerly-breadcrumb-item', className)} {...props} />
+export type BreadcrumbItemProps<T extends ElementType = 'li'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `li`).
+ */
+export function BreadcrumbItem<T extends ElementType = 'li'>({
+  as,
+  className,
+  ...props
+}: BreadcrumbItemProps<T>) {
+  const Tag = as ?? 'li'
+  return <Tag className={cn('sheerly-breadcrumb-item', className)} {...props} />
 }
 
-export function BreadcrumbLink({ className, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) {
-  return <a className={cn('sheerly-breadcrumb-link', className)} {...props} />
+export type BreadcrumbLinkProps<T extends ElementType = 'a'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `a`, e.g.
+ * `as={Link}` for a router link).
+ */
+export function BreadcrumbLink<T extends ElementType = 'a'>({
+  as,
+  className,
+  ...props
+}: BreadcrumbLinkProps<T>) {
+  const Tag = as ?? 'a'
+  return <Tag className={cn('sheerly-breadcrumb-link', className)} {...props} />
 }
 
-export function BreadcrumbPage({ className, ...props }: HTMLAttributes<HTMLSpanElement>) {
+export type BreadcrumbPageProps<T extends ElementType = 'span'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `span`).
+ */
+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"
@@ -35,37 +98,45 @@ export function BreadcrumbPage({ className, ...props }: HTMLAttributes<HTMLSpanE
   )
 }
 
-export function BreadcrumbSeparator({
+export type BreadcrumbSeparatorProps<T extends ElementType = 'li'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `li`).
+ */
+export function BreadcrumbSeparator<T extends ElementType = 'li'>({
+  as,
   className,
-  children,
   ...props
-}: HTMLAttributes<HTMLLIElement>) {
+}: BreadcrumbSeparatorProps<T>) {
+  const Tag = as ?? 'li'
   return (
-    <li
+    <Tag
       role="presentation"
       aria-hidden="true"
       className={cn('sheerly-breadcrumb-separator', className)}
       {...props}
-    >
-      {children}
-    </li>
+    />
   )
 }
 
-export function BreadcrumbEllipsis({
+export type BreadcrumbEllipsisProps<T extends ElementType = 'span'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `span`).
+ */
+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"
       className={cn('sheerly-breadcrumb-ellipsis', className)}
       {...props}
-    >
-      {children}
-    </span>
+    />
   )
 }

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} />
 }