sheerly 0.0.1 → 0.0.3

package/src/pagination.tsx

@@ -1,9 +1,31 @@
-import type { AnchorHTMLAttributes, HTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export function Pagination({ className, ...props }: HTMLAttributes<HTMLElement>) {
+export type PaginationProps<T extends ElementType = 'nav'> = PolymorphicProps<T>
+
+/**
+ * Page navigation. Mark the current page's link with `isActive`.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `nav`).
+ *
+ * @example
+ * <Pagination>
+ *   <PaginationContent>
+ *     <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
+ *     <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
+ *     <PaginationItem><PaginationNext href="#" /></PaginationItem>
+ *   </PaginationContent>
+ * </Pagination>
+ */
+export function Pagination<T extends ElementType = 'nav'>({
+  as,
+  className,
+  ...props
+}: PaginationProps<T>) {
+  const Tag = as ?? 'nav'
   return (
-    <nav
+    <Tag
       role="navigation"
       aria-label="pagination"
       className={cn('sheerly-pagination', className)}
@@ -12,30 +34,56 @@ export function Pagination({ className, ...props }: HTMLAttributes<HTMLElement>)
   )
 }
 
-export function PaginationContent({
+export type PaginationContentProps<T extends ElementType = 'ul'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `ul`).
+ */
+export function PaginationContent<T extends ElementType = 'ul'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLUListElement>) {
-  return <ul className={cn('sheerly-pagination-content', className)} {...props} />
+}: PaginationContentProps<T>) {
+  const Tag = as ?? 'ul'
+  return <Tag className={cn('sheerly-pagination-content', className)} {...props} />
 }
 
-export function PaginationItem({ className, ...props }: HTMLAttributes<HTMLLIElement>) {
-  return <li className={cn('sheerly-pagination-item', className)} {...props} />
-}
+export type PaginationItemProps<T extends ElementType = 'li'> = PolymorphicProps<T>
 
-export interface PaginationLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-  /** Marks the current page (renders like the outline button). */
-  isActive?: boolean
-  'data-role'?: 'previous' | 'next'
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `li`).
+ */
+export function PaginationItem<T extends ElementType = 'li'>({
+  as,
+  className,
+  ...props
+}: PaginationItemProps<T>) {
+  const Tag = as ?? 'li'
+  return <Tag className={cn('sheerly-pagination-item', className)} {...props} />
 }
 
-export function PaginationLink({
+export type PaginationLinkProps<T extends ElementType = 'a'> = PolymorphicProps<
+  T,
+  {
+    /** Marks the current page (renders like the outline button). */
+    isActive?: boolean
+    'data-role'?: 'previous' | 'next'
+  }
+>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `a`, e.g.
+ * `as={Link}` for a router link).
+ */
+export function PaginationLink<T extends ElementType = 'a'>({
+  as,
   className,
   isActive,
   ...props
-}: PaginationLinkProps) {
+}: PaginationLinkProps<T>) {
+  const Tag = as ?? 'a'
   return (
-    <a
+    <Tag
       aria-current={isActive ? 'page' : undefined}
       className={cn('sheerly-pagination-link', className)}
       {...props}
@@ -43,53 +91,77 @@ export function PaginationLink({
   )
 }
 
-export function PaginationPrevious({
+export type PaginationPreviousProps<T extends ElementType = 'a'> = PaginationLinkProps<T> & {
+  /** Visible label. Children override it. */
+  text?: string
+}
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `a`).
+ */
+export function PaginationPrevious<T extends ElementType = 'a'>({
+  as,
   className,
+  isActive,
   text = 'Previous',
   children,
   ...props
-}: PaginationLinkProps & { text?: string }) {
+}: PaginationPreviousProps<T>) {
+  const Tag = as ?? 'a'
   return (
-    <PaginationLink
+    <Tag
       aria-label="Go to previous page"
+      aria-current={isActive ? 'page' : undefined}
       data-role="previous"
-      className={className}
+      className={cn('sheerly-pagination-link', className)}
       {...props}
     >
       {children ?? text}
-    </PaginationLink>
+    </Tag>
   )
 }
 
-export function PaginationNext({
+export type PaginationNextProps<T extends ElementType = 'a'> = PaginationPreviousProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `a`).
+ */
+export function PaginationNext<T extends ElementType = 'a'>({
+  as,
   className,
+  isActive,
   text = 'Next',
   children,
   ...props
-}: PaginationLinkProps & { text?: string }) {
+}: PaginationNextProps<T>) {
+  const Tag = as ?? 'a'
   return (
-    <PaginationLink
+    <Tag
       aria-label="Go to next page"
+      aria-current={isActive ? 'page' : undefined}
       data-role="next"
-      className={className}
+      className={cn('sheerly-pagination-link', className)}
       {...props}
     >
       {children ?? text}
-    </PaginationLink>
+    </Tag>
   )
 }
 
-export function PaginationEllipsis({
+export type PaginationEllipsisProps<T extends ElementType = 'span'> = PolymorphicProps<T>
+
+/**
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `span`).
+ */
+export function PaginationEllipsis<T extends ElementType = 'span'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLSpanElement>) {
+}: PaginationEllipsisProps<T>) {
+  const Tag = as ?? 'span'
   return (
-    <span
-      aria-hidden
-      className={cn('sheerly-pagination-ellipsis', className)}
-      {...props}
-    >
+    <Tag aria-hidden className={cn('sheerly-pagination-ellipsis', className)} {...props}>
       &hellip;
-    </span>
+    </Tag>
   )
 }

package/src/popover.tsx

@@ -1,16 +1,35 @@
-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 PopoverProps = HTMLAttributes<HTMLSpanElement>
+export type PopoverProps<T extends ElementType = 'span'> = PolymorphicProps<T>
 
-/** Wrapper carrying the anchor. Nest the trigger button + content inside. */
-export function Popover({ className, ...props }: PopoverProps) {
-  return <span className={cn('sheerly-popover', className)} {...props} />
+/**
+ * Wrapper carrying the anchor. Nest the trigger button + content inside.
+ *
+ * @example
+ * <Popover>
+ *   <Button commandfor="p" command="toggle-popover">Open</Button>
+ *   <PopoverContent id="p" popover>Place content here.</PopoverContent>
+ * </Popover>
+ */
+export function Popover<T extends ElementType = 'span'>({
+  as,
+  className,
+  ...props
+}: PopoverProps<T>) {
+  const Tag = as ?? 'span'
+  return <Tag className={cn('sheerly-popover', className)} {...props} />
 }
 
-export type PopoverContentProps = HTMLAttributes<HTMLDivElement>
+export type PopoverContentProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
 /** The floating panel. Give it `popover` and an `id` matched by the trigger's `commandfor`. */
-export function PopoverContent({ className, ...props }: PopoverContentProps) {
-  return <div className={cn('sheerly-popover-content', className)} {...props} />
+export function PopoverContent<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: PopoverContentProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-popover-content', className)} {...props} />
 }

package/src/progress.tsx

@@ -1,5 +1,5 @@
 import type { ProgressHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export interface ProgressProps extends ProgressHTMLAttributes<HTMLProgressElement> {
   'data-variant'?:
@@ -14,6 +14,12 @@ export interface ProgressProps extends ProgressHTMLAttributes<HTMLProgressElemen
   'data-size'?: 'sm' | 'default' | 'lg'
 }
 
+/**
+ * A determinate progress bar. Set `value` (and `max`, default 1).
+ *
+ * @example
+ * <Progress value={60} max={100} data-variant="success" />
+ */
 export function Progress({ className, ...props }: ProgressProps) {
   return <progress className={cn('sheerly-progress', className)} {...props} />
 }

package/src/radio.tsx

@@ -1,14 +1,29 @@
-import type { HTMLAttributes, InputHTMLAttributes } from 'react'
-import { cn } from './cn'
+import type { ElementType, InputHTMLAttributes } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
 
-export type RadioGroupProps = HTMLAttributes<HTMLDivElement>
+export type RadioGroupProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function RadioGroup({ className, ...props }: RadioGroupProps) {
-  return <div className={cn('sheerly-radio-group', className)} {...props} />
+export function RadioGroup<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: RadioGroupProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-radio-group', className)} {...props} />
 }
 
 export type RadioProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
 
+/**
+ * A radio `<input>`. Share a `name` and wrap options in a <RadioGroup>.
+ *
+ * @example
+ * <RadioGroup>
+ *   <Label><Radio name="plan" value="free" defaultChecked /> Free</Label>
+ *   <Label><Radio name="plan" value="pro" /> Pro</Label>
+ * </RadioGroup>
+ */
 export function Radio({ className, ...props }: RadioProps) {
   return <input type="radio" className={cn('sheerly-radio', className)} {...props} />
 }

package/src/scrollbar.css

@@ -0,0 +1,56 @@
+/*
+ * Scrollbar — a sheerly-styled scrollbar for any overflow container.
+ * Apply `.sheerly-scrollbar` to a scrollable element to replace the native
+ * scrollbar with a thin, theme-tinted one (matching the select picker).
+ * You still set the element's own size + overflow (e.g. `max-height` +
+ * `overflow-y: auto`), or use a `data-orientation` helper below.
+ *
+ * Usage:
+ *   <div class="sheerly-scrollbar" style="max-height: 200px; overflow-y: auto">…</div>
+ *   <div class="sheerly-scrollbar" data-orientation="vertical" style="max-height: 200px">…</div>
+ *   <div class="sheerly-scrollbar" data-orientation="horizontal">…</div>
+ *
+ * Latest Chrome only — uses standard `scrollbar-width`/`scrollbar-color` plus
+ * `::-webkit-scrollbar-*` for the fuller styled look.
+ */
+.sheerly-scrollbar {
+  /* Standard properties (thin thumb tinted from the foreground). */
+  scrollbar-width: thin;
+  scrollbar-color: oklch(from var(--sheerly-foreground) l c h / 20%) transparent;
+
+  /* WebKit/Blink styled scrollbar. */
+  &::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    border: 2px solid transparent;
+    border-radius: var(--sheerly-radius-full);
+    background-clip: padding-box;
+    background-color: oklch(from var(--sheerly-foreground) l c h / 20%);
+  }
+
+  &::-webkit-scrollbar-thumb:hover {
+    background-color: oklch(from var(--sheerly-foreground) l c h / 35%);
+  }
+
+  &::-webkit-scrollbar-corner {
+    background: transparent;
+  }
+
+  /* Orientation helpers set the matching overflow so the class is enough. */
+  &[data-orientation="vertical"] {
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  &[data-orientation="horizontal"] {
+    overflow-x: auto;
+    overflow-y: hidden;
+  }
+}

package/src/scrollbar.tsx

@@ -0,0 +1,28 @@
+import type { ElementType } from 'react'
+import { cn } from './utils/cn'
+import type { PolymorphicProps } from './utils/polymorphic'
+
+export type ScrollbarProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-orientation'?: 'vertical' | 'horizontal' }
+>
+
+/**
+ * A scroll container with a thin, theme-tinted scrollbar (matching the select
+ * picker). Set the element's own size + overflow inline, or use
+ * `data-orientation` to have the matching overflow applied for you.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Scrollbar data-orientation="vertical" style={{ maxHeight: 200 }}>…</Scrollbar>
+ * <Scrollbar style={{ maxHeight: 200, overflowY: 'auto' }}>…</Scrollbar>
+ */
+export function Scrollbar<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: ScrollbarProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-scrollbar', className)} {...props} />
+}

package/src/select.css

@@ -12,6 +12,7 @@
   gap: 8px;
   border-radius: var(--sheerly-radius-lg);
   border: 1px solid var(--sheerly-input);
+  box-sizing: border-box;
   background-color: transparent;
   padding: 0 12px;
   font-family: "Geist Sans", system-ui, -apple-system, sans-serif;
@@ -97,6 +98,29 @@
   overflow-y: auto;
   opacity: 0;
   transition: all 0.2s allow-discrete;
+
+  /* Sheerly-styled scrollbar (replaces the native one) */
+  scrollbar-width: thin;
+  scrollbar-color: oklch(from var(--sheerly-foreground) l c h / 20%) transparent;
+
+  &::-webkit-scrollbar {
+    width: 8px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    border: 2px solid transparent;
+    border-radius: var(--sheerly-radius-full);
+    background-clip: padding-box;
+    background-color: oklch(from var(--sheerly-foreground) l c h / 20%);
+  }
+
+  &::-webkit-scrollbar-thumb:hover {
+    background-color: oklch(from var(--sheerly-foreground) l c h / 35%);
+  }
 }
 
 .sheerly-select:open::picker(select) {

package/src/select.tsx

@@ -1,5 +1,5 @@
 import type { SelectHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
   'data-size'?: 'sm' | 'default' | 'lg'
@@ -9,6 +9,12 @@ export interface SelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
  * Uses the customizable-select API. Requires
  * `<button><selectedcontent></selectedcontent></button>` as the first child,
  * which this wrapper injects before the consumer's <option>s.
+ *
+ * @example
+ * <Select defaultValue="apple">
+ *   <option value="apple">Apple</option>
+ *   <option value="banana">Banana</option>
+ * </Select>
  */
 export function Select({ className, children, ...props }: SelectProps) {
   return (

package/src/separator.tsx

@@ -1,10 +1,26 @@
-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 SeparatorProps extends HTMLAttributes<HTMLDivElement> {
-  'data-orientation'?: 'horizontal' | 'vertical'
-}
+export type SeparatorProps<T extends ElementType = 'div'> = PolymorphicProps<
+  T,
+  { 'data-orientation'?: 'horizontal' | 'vertical' }
+>
 
-export function Separator({ className, ...props }: SeparatorProps) {
-  return <div className={cn('sheerly-separator', className)} {...props} />
+/**
+ * A divider line. Set `data-orientation="vertical"` for a vertical rule.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`, e.g.
+ * `as="hr"`).
+ *
+ * @example
+ * <Separator />
+ */
+export function Separator<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SeparatorProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-separator', className)} {...props} />
 }

package/src/sheet.tsx

@@ -1,5 +1,6 @@
-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'
 
 export interface SheetProps extends DialogHTMLAttributes<HTMLDialogElement> {
   'data-side'?: 'right' | 'left' | 'top' | 'bottom'
@@ -9,32 +10,71 @@ export interface SheetProps extends DialogHTMLAttributes<HTMLDialogElement> {
  * Native <dialog> that slides in from an edge. Open via invoker command
  * (`command="show-modal"`) or `.showModal()`. Add `closedby="any"` for
  * light-dismiss.
+ *
+ * @example
+ * <button commandfor="s" command="show-modal">Open</button>
+ * <Sheet id="s" data-side="right" closedby="any">
+ *   <SheetHeader><SheetTitle>Filters</SheetTitle></SheetHeader>
+ *   <SheetBody>…</SheetBody>
+ * </Sheet>
  */
 export function Sheet({ className, ...props }: SheetProps) {
   return <dialog className={cn('sheerly-sheet', className)} {...props} />
 }
 
-export function SheetHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-sheet-header', className)} {...props} />
+export type SheetHeaderProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function SheetHeader<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SheetHeaderProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-sheet-header', className)} {...props} />
 }
 
-export function SheetTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
-  return <h3 className={cn('sheerly-sheet-title', className)} {...props} />
+export type SheetTitleProps<T extends ElementType = 'h3'> = PolymorphicProps<T>
+
+export function SheetTitle<T extends ElementType = 'h3'>({
+  as,
+  className,
+  ...props
+}: SheetTitleProps<T>) {
+  const Tag = as ?? 'h3'
+  return <Tag className={cn('sheerly-sheet-title', className)} {...props} />
 }
 
-export function SheetDescription({
+export type SheetDescriptionProps<T extends ElementType = 'p'> = PolymorphicProps<T>
+
+export function SheetDescription<T extends ElementType = 'p'>({
+  as,
   className,
   ...props
-}: HTMLAttributes<HTMLParagraphElement>) {
-  return <p className={cn('sheerly-sheet-description', className)} {...props} />
+}: SheetDescriptionProps<T>) {
+  const Tag = as ?? 'p'
+  return <Tag className={cn('sheerly-sheet-description', className)} {...props} />
 }
 
-export function SheetBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-sheet-body', className)} {...props} />
+export type SheetBodyProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function SheetBody<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SheetBodyProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-sheet-body', className)} {...props} />
 }
 
-export function SheetFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn('sheerly-sheet-footer', className)} {...props} />
+export type SheetFooterProps<T extends ElementType = 'div'> = PolymorphicProps<T>
+
+export function SheetFooter<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SheetFooterProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-sheet-footer', className)} {...props} />
 }
 
 export function SheetClose({

package/src/skeleton.tsx

@@ -1,8 +1,22 @@
-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 SkeletonProps = HTMLAttributes<HTMLDivElement>
+export type SkeletonProps<T extends ElementType = 'div'> = PolymorphicProps<T>
 
-export function Skeleton({ className, ...props }: SkeletonProps) {
-  return <div className={cn('sheerly-skeleton', className)} {...props} />
+/**
+ * A pulsing placeholder. Set width/height/border-radius inline.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `div`).
+ *
+ * @example
+ * <Skeleton style={{ width: 200, height: 20, borderRadius: 6 }} />
+ */
+export function Skeleton<T extends ElementType = 'div'>({
+  as,
+  className,
+  ...props
+}: SkeletonProps<T>) {
+  const Tag = as ?? 'div'
+  return <Tag className={cn('sheerly-skeleton', className)} {...props} />
 }

package/src/slider.tsx

@@ -1,8 +1,14 @@
 import type { InputHTMLAttributes } from 'react'
-import { cn } from './cn'
+import { cn } from './utils/cn'
 
 export type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>
 
+/**
+ * A range `<input>`. Set `min` / `max` / `step` / `value`.
+ *
+ * @example
+ * <Slider min={0} max={100} defaultValue={50} />
+ */
 export function Slider({ className, ...props }: SliderProps) {
   return <input type="range" className={cn('sheerly-slider', className)} {...props} />
 }

package/src/spinner.tsx

@@ -1,24 +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 SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
-  'data-size'?: 'sm' | 'default' | 'md' | 'lg'
-}
+export type SpinnerProps<T extends ElementType = 'span'> = PolymorphicProps<
+  T,
+  { 'data-size'?: 'sm' | 'default' | 'md' | 'lg' }
+>
 
 /**
  * Loading spinner. The glyph is embedded in CSS (masked ::before), so no SVG
  * child is needed — this renders a bare <span>. It inherits the current text
  * color. Pass an <svg> child if you prefer to ship your own icon.
+ *
+ * Polymorphic: pass `as` to change the rendered tag (defaults to `span`).
+ *
+ * @example
+ * <Spinner data-size="lg" />
  */
-export function Spinner({ className, children, ...props }: SpinnerProps) {
+export function Spinner<T extends ElementType = 'span'>({
+  as,
+  className,
+  children,
+  ...props
+}: SpinnerProps<T>) {
+  const Tag = as ?? 'span'
   return (
-    <span
+    <Tag
       className={cn('sheerly-spinner', className)}
       role="status"
       aria-label="Loading"
       {...props}
     >
       {children}
-    </span>
+    </Tag>
   )
 }