@sproutsocial/seeds-react-visually-hidden 1.0.32 → 1.0.34

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 yarn run v1.22.22
-$ tsup --dts
+$ tsup --dts && cp src/visually-hidden.css dist/visually-hidden.css
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.5.0
@@ -8,14 +8,14 @@ $ tsup --dts
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-CJS dist/index.js     2.11 KB
-CJS dist/index.js.map 961.00 B
-CJS ⚡️ Build success in 81ms
-ESM dist/esm/index.js     402.00 B
-ESM dist/esm/index.js.map 842.00 B
+CJS dist/index.js     3.53 KB
+CJS dist/index.js.map 3.37 KB
+CJS ⚡️ Build success in 82ms
+ESM dist/esm/index.js     1.63 KB
+ESM dist/esm/index.js.map 3.24 KB
 ESM ⚡️ Build success in 81ms
 DTS Build start
-DTS ⚡️ Build success in 4401ms
-DTS dist/index.d.ts  481.00 B
-DTS dist/index.d.mts 481.00 B
-Done in 5.51s.
+DTS ⚡️ Build success in 3776ms
+DTS dist/index.d.ts  482.00 B
+DTS dist/index.d.mts 482.00 B
+Done in 4.84s.

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @sproutsocial/seeds-react-visually-hidden
 
+## 1.0.34
+
+### Patch Changes
+
+- Updated dependencies [57372fe]
+  - @sproutsocial/seeds-react-theme@4.6.0
+  - @sproutsocial/seeds-react-mixins@4.3.17
+
+## 1.0.33
+
+### Patch Changes
+
+- a33ef79: Add a Tailwind/CSS-class rendering path to VisuallyHidden using the Seeds hybrid pattern. Plain usage now renders the semantic `seeds-visually-hidden` class, while styled-system props and styled-components extensions retain the existing styled-components fallback. The component's public API and loose prop type remain unchanged, and the new CSS ships through package dist and `@sproutsocial/racine/css/components`.
+  - @sproutsocial/seeds-react-theme@4.5.1
+  - @sproutsocial/seeds-react-mixins@4.3.16
+
 ## 1.0.32
 
 ### Patch Changes

package/dist/esm/index.js

@@ -1,13 +1,52 @@
-// src/VisuallyHidden.tsx
+// src/VisuallyHiddenHybrid.tsx
+import { needsStyledComponents } from "@sproutsocial/seeds-react-system-props";
+
+// src/VisuallyHiddenStyled.tsx
 import styled from "styled-components";
 import { visuallyHidden } from "@sproutsocial/seeds-react-mixins";
 import { jsx } from "react/jsx-runtime";
 var StyledVisuallyHidden = styled.span`
   ${visuallyHidden}
 `;
-var VisuallyHidden = (props) => {
-  return /* @__PURE__ */ jsx(StyledVisuallyHidden, { ...props });
+var VisuallyHiddenStyled = (props) => /* @__PURE__ */ jsx(StyledVisuallyHidden, { ...props });
+
+// src/VisuallyHiddenTailwind.tsx
+import isPropValid from "@emotion/is-prop-valid";
+import * as React from "react";
+var mergeClassNames = (...classes) => classes.filter(Boolean).join(" ");
+var VisuallyHiddenTailwind = ({
+  as,
+  children,
+  className,
+  ...rest
+}) => {
+  const Element = as ?? "span";
+  const forwardedProps = typeof Element === "string" ? Object.fromEntries(
+    Object.entries(rest).filter(([name]) => isPropValid(name))
+  ) : rest;
+  return React.createElement(
+    Element,
+    {
+      ...forwardedProps,
+      className: mergeClassNames("seeds-visually-hidden", className)
+    },
+    children
+  );
+};
+VisuallyHiddenTailwind.displayName = "VisuallyHiddenTailwind";
+
+// src/VisuallyHiddenHybrid.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var VisuallyHiddenHybrid = (props) => {
+  if (needsStyledComponents(props)) {
+    return /* @__PURE__ */ jsx2(VisuallyHiddenStyled, { ...props });
+  }
+  return /* @__PURE__ */ jsx2(VisuallyHiddenTailwind, { ...props });
 };
+
+// src/VisuallyHidden.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+var VisuallyHidden = (props) => /* @__PURE__ */ jsx3(VisuallyHiddenHybrid, { ...props });
 export {
   VisuallyHidden
 };

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/VisuallyHidden.tsx"],"sourcesContent":["import styled from \"styled-components\";\nimport { visuallyHidden } from \"@sproutsocial/seeds-react-mixins\";\nimport type { ComponentPropsWithRef } from \"react\";\n\nconst StyledVisuallyHidden = styled.span`\n  ${visuallyHidden}\n`;\n\nexport type VisuallyHiddenProps = ComponentPropsWithRef<\n  typeof StyledVisuallyHidden\n>;\n\n// This wrapper component is needed for react-docgen to work.\n// It has issues with generating docs for the styled component directly.\nexport const VisuallyHidden = (props: VisuallyHiddenProps) => {\n  return <StyledVisuallyHidden {...props} />;\n};\n"],"mappings":";AAAA,OAAO,YAAY;AACnB,SAAS,sBAAsB;AActB;AAXT,IAAM,uBAAuB,OAAO;AAAA,IAChC,cAAc;AAAA;AASX,IAAM,iBAAiB,CAAC,UAA+B;AAC5D,SAAO,oBAAC,wBAAsB,GAAG,OAAO;AAC1C;","names":[]}
+{"version":3,"sources":["../../src/VisuallyHiddenHybrid.tsx","../../src/VisuallyHiddenStyled.tsx","../../src/VisuallyHiddenTailwind.tsx","../../src/VisuallyHidden.tsx"],"sourcesContent":["import { needsStyledComponents } from \"@sproutsocial/seeds-react-system-props\";\nimport {\n  VisuallyHiddenStyled,\n  type VisuallyHiddenProps,\n} from \"./VisuallyHiddenStyled\";\nimport { VisuallyHiddenTailwind } from \"./VisuallyHiddenTailwind\";\n\nexport const VisuallyHiddenHybrid = (props: VisuallyHiddenProps) => {\n  if (needsStyledComponents(props)) {\n    return <VisuallyHiddenStyled {...props} />;\n  }\n\n  return <VisuallyHiddenTailwind {...props} />;\n};\n","import styled from \"styled-components\";\nimport { visuallyHidden } from \"@sproutsocial/seeds-react-mixins\";\nimport type { ComponentPropsWithRef } from \"react\";\n\nconst StyledVisuallyHidden = styled.span`\n  ${visuallyHidden}\n`;\n\nexport type VisuallyHiddenProps = ComponentPropsWithRef<\n  typeof StyledVisuallyHidden\n>;\n\nexport const VisuallyHiddenStyled = (props: VisuallyHiddenProps) => (\n  <StyledVisuallyHidden {...props} />\n);\n","import isPropValid from \"@emotion/is-prop-valid\";\nimport * as React from \"react\";\nimport type { VisuallyHiddenProps } from \"./VisuallyHiddenStyled\";\n\nconst mergeClassNames = (...classes: Array<string | undefined>) =>\n  classes.filter(Boolean).join(\" \");\n\nexport const VisuallyHiddenTailwind = ({\n  as,\n  children,\n  className,\n  ...rest\n}: VisuallyHiddenProps) => {\n  const Element = (as ?? \"span\") as React.ElementType;\n  const forwardedProps =\n    typeof Element === \"string\"\n      ? Object.fromEntries(\n          Object.entries(rest).filter(([name]) => isPropValid(name))\n        )\n      : rest;\n\n  return React.createElement(\n    Element,\n    {\n      ...forwardedProps,\n      className: mergeClassNames(\"seeds-visually-hidden\", className),\n    },\n    children\n  );\n};\n\nVisuallyHiddenTailwind.displayName = \"VisuallyHiddenTailwind\";\n","import { VisuallyHiddenHybrid } from \"./VisuallyHiddenHybrid\";\nimport type { VisuallyHiddenProps } from \"./VisuallyHiddenStyled\";\n\nexport type { VisuallyHiddenProps };\n\n// This wrapper component is needed for react-docgen to work.\n// It has issues with generating docs for the implementation directly.\nexport const VisuallyHidden = (props: VisuallyHiddenProps) => (\n  <VisuallyHiddenHybrid {...props} />\n);\n"],"mappings":";AAAA,SAAS,6BAA6B;;;ACAtC,OAAO,YAAY;AACnB,SAAS,sBAAsB;AAY7B;AATF,IAAM,uBAAuB,OAAO;AAAA,IAChC,cAAc;AAAA;AAOX,IAAM,uBAAuB,CAAC,UACnC,oBAAC,wBAAsB,GAAG,OAAO;;;ACbnC,OAAO,iBAAiB;AACxB,YAAY,WAAW;AAGvB,IAAM,kBAAkB,IAAI,YAC1B,QAAQ,OAAO,OAAO,EAAE,KAAK,GAAG;AAE3B,IAAM,yBAAyB,CAAC;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA2B;AACzB,QAAM,UAAW,MAAM;AACvB,QAAM,iBACJ,OAAO,YAAY,WACf,OAAO;AAAA,IACL,OAAO,QAAQ,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,MAAM,YAAY,IAAI,CAAC;AAAA,EAC3D,IACA;AAEN,SAAa;AAAA,IACX;AAAA,IACA;AAAA,MACE,GAAG;AAAA,MACH,WAAW,gBAAgB,yBAAyB,SAAS;AAAA,IAC/D;AAAA,IACA;AAAA,EACF;AACF;AAEA,uBAAuB,cAAc;;;AFtB1B,gBAAAA,YAAA;AAFJ,IAAM,uBAAuB,CAAC,UAA+B;AAClE,MAAI,sBAAsB,KAAK,GAAG;AAChC,WAAO,gBAAAA,KAAC,wBAAsB,GAAG,OAAO;AAAA,EAC1C;AAEA,SAAO,gBAAAA,KAAC,0BAAwB,GAAG,OAAO;AAC5C;;;AGLE,gBAAAC,YAAA;AADK,IAAM,iBAAiB,CAAC,UAC7B,gBAAAA,KAAC,wBAAsB,GAAG,OAAO;","names":["jsx","jsx"]}

package/dist/index.d.mts

@@ -4,6 +4,7 @@ import { ComponentPropsWithRef } from 'react';
 
 declare const StyledVisuallyHidden: styled_components.StyledComponent<"span", any, {}, never>;
 type VisuallyHiddenProps = ComponentPropsWithRef<typeof StyledVisuallyHidden>;
+
 declare const VisuallyHidden: (props: VisuallyHiddenProps) => react_jsx_runtime.JSX.Element;
 
 export { VisuallyHidden, type VisuallyHiddenProps };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { ComponentPropsWithRef } from 'react';
 
 declare const StyledVisuallyHidden: styled_components.StyledComponent<"span", any, {}, never>;
 type VisuallyHiddenProps = ComponentPropsWithRef<typeof StyledVisuallyHidden>;
+
 declare const VisuallyHidden: (props: VisuallyHiddenProps) => react_jsx_runtime.JSX.Element;
 
 export { VisuallyHidden, type VisuallyHiddenProps };

package/dist/index.js

@@ -34,16 +34,55 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/VisuallyHidden.tsx
+// src/VisuallyHiddenHybrid.tsx
+var import_seeds_react_system_props = require("@sproutsocial/seeds-react-system-props");
+
+// src/VisuallyHiddenStyled.tsx
 var import_styled_components = __toESM(require("styled-components"));
 var import_seeds_react_mixins = require("@sproutsocial/seeds-react-mixins");
 var import_jsx_runtime = require("react/jsx-runtime");
 var StyledVisuallyHidden = import_styled_components.default.span`
   ${import_seeds_react_mixins.visuallyHidden}
 `;
-var VisuallyHidden = (props) => {
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(StyledVisuallyHidden, { ...props });
+var VisuallyHiddenStyled = (props) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(StyledVisuallyHidden, { ...props });
+
+// src/VisuallyHiddenTailwind.tsx
+var import_is_prop_valid = __toESM(require("@emotion/is-prop-valid"));
+var React = __toESM(require("react"));
+var mergeClassNames = (...classes) => classes.filter(Boolean).join(" ");
+var VisuallyHiddenTailwind = ({
+  as,
+  children,
+  className,
+  ...rest
+}) => {
+  const Element = as ?? "span";
+  const forwardedProps = typeof Element === "string" ? Object.fromEntries(
+    Object.entries(rest).filter(([name]) => (0, import_is_prop_valid.default)(name))
+  ) : rest;
+  return React.createElement(
+    Element,
+    {
+      ...forwardedProps,
+      className: mergeClassNames("seeds-visually-hidden", className)
+    },
+    children
+  );
+};
+VisuallyHiddenTailwind.displayName = "VisuallyHiddenTailwind";
+
+// src/VisuallyHiddenHybrid.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var VisuallyHiddenHybrid = (props) => {
+  if ((0, import_seeds_react_system_props.needsStyledComponents)(props)) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(VisuallyHiddenStyled, { ...props });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(VisuallyHiddenTailwind, { ...props });
 };
+
+// src/VisuallyHidden.tsx
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var VisuallyHidden = (props) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(VisuallyHiddenHybrid, { ...props });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   VisuallyHidden

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/VisuallyHidden.tsx"],"sourcesContent":["export * from \"./VisuallyHidden\";\n","import styled from \"styled-components\";\nimport { visuallyHidden } from \"@sproutsocial/seeds-react-mixins\";\nimport type { ComponentPropsWithRef } from \"react\";\n\nconst StyledVisuallyHidden = styled.span`\n  ${visuallyHidden}\n`;\n\nexport type VisuallyHiddenProps = ComponentPropsWithRef<\n  typeof StyledVisuallyHidden\n>;\n\n// This wrapper component is needed for react-docgen to work.\n// It has issues with generating docs for the styled component directly.\nexport const VisuallyHidden = (props: VisuallyHiddenProps) => {\n  return <StyledVisuallyHidden {...props} />;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,+BAAmB;AACnB,gCAA+B;AActB;AAXT,IAAM,uBAAuB,yBAAAA,QAAO;AAAA,IAChC,wCAAc;AAAA;AASX,IAAM,iBAAiB,CAAC,UAA+B;AAC5D,SAAO,4CAAC,wBAAsB,GAAG,OAAO;AAC1C;","names":["styled"]}
+{"version":3,"sources":["../src/index.ts","../src/VisuallyHiddenHybrid.tsx","../src/VisuallyHiddenStyled.tsx","../src/VisuallyHiddenTailwind.tsx","../src/VisuallyHidden.tsx"],"sourcesContent":["export * from \"./VisuallyHidden\";\n","import { needsStyledComponents } from \"@sproutsocial/seeds-react-system-props\";\nimport {\n  VisuallyHiddenStyled,\n  type VisuallyHiddenProps,\n} from \"./VisuallyHiddenStyled\";\nimport { VisuallyHiddenTailwind } from \"./VisuallyHiddenTailwind\";\n\nexport const VisuallyHiddenHybrid = (props: VisuallyHiddenProps) => {\n  if (needsStyledComponents(props)) {\n    return <VisuallyHiddenStyled {...props} />;\n  }\n\n  return <VisuallyHiddenTailwind {...props} />;\n};\n","import styled from \"styled-components\";\nimport { visuallyHidden } from \"@sproutsocial/seeds-react-mixins\";\nimport type { ComponentPropsWithRef } from \"react\";\n\nconst StyledVisuallyHidden = styled.span`\n  ${visuallyHidden}\n`;\n\nexport type VisuallyHiddenProps = ComponentPropsWithRef<\n  typeof StyledVisuallyHidden\n>;\n\nexport const VisuallyHiddenStyled = (props: VisuallyHiddenProps) => (\n  <StyledVisuallyHidden {...props} />\n);\n","import isPropValid from \"@emotion/is-prop-valid\";\nimport * as React from \"react\";\nimport type { VisuallyHiddenProps } from \"./VisuallyHiddenStyled\";\n\nconst mergeClassNames = (...classes: Array<string | undefined>) =>\n  classes.filter(Boolean).join(\" \");\n\nexport const VisuallyHiddenTailwind = ({\n  as,\n  children,\n  className,\n  ...rest\n}: VisuallyHiddenProps) => {\n  const Element = (as ?? \"span\") as React.ElementType;\n  const forwardedProps =\n    typeof Element === \"string\"\n      ? Object.fromEntries(\n          Object.entries(rest).filter(([name]) => isPropValid(name))\n        )\n      : rest;\n\n  return React.createElement(\n    Element,\n    {\n      ...forwardedProps,\n      className: mergeClassNames(\"seeds-visually-hidden\", className),\n    },\n    children\n  );\n};\n\nVisuallyHiddenTailwind.displayName = \"VisuallyHiddenTailwind\";\n","import { VisuallyHiddenHybrid } from \"./VisuallyHiddenHybrid\";\nimport type { VisuallyHiddenProps } from \"./VisuallyHiddenStyled\";\n\nexport type { VisuallyHiddenProps };\n\n// This wrapper component is needed for react-docgen to work.\n// It has issues with generating docs for the implementation directly.\nexport const VisuallyHidden = (props: VisuallyHiddenProps) => (\n  <VisuallyHiddenHybrid {...props} />\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,sCAAsC;;;ACAtC,+BAAmB;AACnB,gCAA+B;AAY7B;AATF,IAAM,uBAAuB,yBAAAA,QAAO;AAAA,IAChC,wCAAc;AAAA;AAOX,IAAM,uBAAuB,CAAC,UACnC,4CAAC,wBAAsB,GAAG,OAAO;;;ACbnC,2BAAwB;AACxB,YAAuB;AAGvB,IAAM,kBAAkB,IAAI,YAC1B,QAAQ,OAAO,OAAO,EAAE,KAAK,GAAG;AAE3B,IAAM,yBAAyB,CAAC;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA2B;AACzB,QAAM,UAAW,MAAM;AACvB,QAAM,iBACJ,OAAO,YAAY,WACf,OAAO;AAAA,IACL,OAAO,QAAQ,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,UAAM,qBAAAC,SAAY,IAAI,CAAC;AAAA,EAC3D,IACA;AAEN,SAAa;AAAA,IACX;AAAA,IACA;AAAA,MACE,GAAG;AAAA,MACH,WAAW,gBAAgB,yBAAyB,SAAS;AAAA,IAC/D;AAAA,IACA;AAAA,EACF;AACF;AAEA,uBAAuB,cAAc;;;AFtB1B,IAAAC,sBAAA;AAFJ,IAAM,uBAAuB,CAAC,UAA+B;AAClE,UAAI,uDAAsB,KAAK,GAAG;AAChC,WAAO,6CAAC,wBAAsB,GAAG,OAAO;AAAA,EAC1C;AAEA,SAAO,6CAAC,0BAAwB,GAAG,OAAO;AAC5C;;;AGLE,IAAAC,sBAAA;AADK,IAAM,iBAAiB,CAAC,UAC7B,6CAAC,wBAAsB,GAAG,OAAO;","names":["styled","isPropValid","import_jsx_runtime","import_jsx_runtime"]}

package/dist/visually-hidden.css

@@ -0,0 +1,12 @@
+@layer components {
+  .seeds-visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    border: 0;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutsocial/seeds-react-visually-hidden",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "Seeds React VisuallyHidden",
   "author": "Sprout Social, Inc.",
   "license": "MIT",
@@ -8,8 +8,8 @@
   "module": "dist/esm/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsup --dts",
-    "build:debug": "tsup --dts --metafile",
+    "build": "tsup --dts && cp src/visually-hidden.css dist/visually-hidden.css",
+    "build:debug": "tsup --dts --metafile && cp src/visually-hidden.css dist/visually-hidden.css",
     "dev": "tsup --watch --dts",
     "clean": "rm -rf .turbo dist",
     "clean:modules": "rm -rf node_modules",
@@ -17,10 +17,14 @@
     "test": "jest",
     "test:watch": "jest --watch --coverage=false"
   },
+  "sideEffects": [
+    "**/*.css"
+  ],
   "dependencies": {
-    "@sproutsocial/seeds-react-theme": "^4.5.0",
+    "@emotion/is-prop-valid": "^1.1.0",
+    "@sproutsocial/seeds-react-theme": "^4.6.0",
     "@sproutsocial/seeds-react-system-props": "^3.2.1",
-    "@sproutsocial/seeds-react-mixins": "^4.3.15"
+    "@sproutsocial/seeds-react-mixins": "^4.3.17"
   },
   "devDependencies": {
     "@types/react": "^18.0.0",

package/src/VisuallyHidden.stories.tsx

@@ -26,3 +26,12 @@ export const Default: Story = {
     </Text>
   ),
 };
+
+export const TailwindUtilityOverride: Story = {
+  render: () => (
+    <VisuallyHidden className="static m-0 h-auto w-auto overflow-visible">
+      This text is visible because consumer utilities override the layered
+      component styles.
+    </VisuallyHidden>
+  ),
+};

package/src/VisuallyHidden.tsx

@@ -1,17 +1,10 @@
-import styled from "styled-components";
-import { visuallyHidden } from "@sproutsocial/seeds-react-mixins";
-import type { ComponentPropsWithRef } from "react";
+import { VisuallyHiddenHybrid } from "./VisuallyHiddenHybrid";
+import type { VisuallyHiddenProps } from "./VisuallyHiddenStyled";
 
-const StyledVisuallyHidden = styled.span`
-  ${visuallyHidden}
-`;
-
-export type VisuallyHiddenProps = ComponentPropsWithRef<
-  typeof StyledVisuallyHidden
->;
+export type { VisuallyHiddenProps };
 
 // This wrapper component is needed for react-docgen to work.
-// It has issues with generating docs for the styled component directly.
-export const VisuallyHidden = (props: VisuallyHiddenProps) => {
-  return <StyledVisuallyHidden {...props} />;
-};
+// It has issues with generating docs for the implementation directly.
+export const VisuallyHidden = (props: VisuallyHiddenProps) => (
+  <VisuallyHiddenHybrid {...props} />
+);

package/src/VisuallyHiddenHybrid.tsx

@@ -0,0 +1,14 @@
+import { needsStyledComponents } from "@sproutsocial/seeds-react-system-props";
+import {
+  VisuallyHiddenStyled,
+  type VisuallyHiddenProps,
+} from "./VisuallyHiddenStyled";
+import { VisuallyHiddenTailwind } from "./VisuallyHiddenTailwind";
+
+export const VisuallyHiddenHybrid = (props: VisuallyHiddenProps) => {
+  if (needsStyledComponents(props)) {
+    return <VisuallyHiddenStyled {...props} />;
+  }
+
+  return <VisuallyHiddenTailwind {...props} />;
+};

package/src/VisuallyHiddenStyled.tsx

@@ -0,0 +1,15 @@
+import styled from "styled-components";
+import { visuallyHidden } from "@sproutsocial/seeds-react-mixins";
+import type { ComponentPropsWithRef } from "react";
+
+const StyledVisuallyHidden = styled.span`
+  ${visuallyHidden}
+`;
+
+export type VisuallyHiddenProps = ComponentPropsWithRef<
+  typeof StyledVisuallyHidden
+>;
+
+export const VisuallyHiddenStyled = (props: VisuallyHiddenProps) => (
+  <StyledVisuallyHidden {...props} />
+);

package/src/VisuallyHiddenTailwind.tsx

@@ -0,0 +1,32 @@
+import isPropValid from "@emotion/is-prop-valid";
+import * as React from "react";
+import type { VisuallyHiddenProps } from "./VisuallyHiddenStyled";
+
+const mergeClassNames = (...classes: Array<string | undefined>) =>
+  classes.filter(Boolean).join(" ");
+
+export const VisuallyHiddenTailwind = ({
+  as,
+  children,
+  className,
+  ...rest
+}: VisuallyHiddenProps) => {
+  const Element = (as ?? "span") as React.ElementType;
+  const forwardedProps =
+    typeof Element === "string"
+      ? Object.fromEntries(
+          Object.entries(rest).filter(([name]) => isPropValid(name))
+        )
+      : rest;
+
+  return React.createElement(
+    Element,
+    {
+      ...forwardedProps,
+      className: mergeClassNames("seeds-visually-hidden", className),
+    },
+    children
+  );
+};
+
+VisuallyHiddenTailwind.displayName = "VisuallyHiddenTailwind";

package/src/__tests__/VisuallyHidden.css.test.ts

@@ -0,0 +1,22 @@
+/* eslint-env jest, node */
+import fs from "fs";
+import path from "path";
+
+const cssPath = path.resolve(__dirname, "../visually-hidden.css");
+
+describe("VisuallyHidden CSS", () => {
+  it("defines the semantic class in the components layer with the legacy declarations", () => {
+    const css = fs.readFileSync(cssPath, "utf8");
+
+    expect(css).toContain("@layer components");
+    expect(css).toContain(".seeds-visually-hidden");
+    expect(css).toContain("position: absolute;");
+    expect(css).toContain("width: 1px;");
+    expect(css).toContain("height: 1px;");
+    expect(css).toContain("padding: 0;");
+    expect(css).toContain("margin: -1px;");
+    expect(css).toContain("overflow: hidden;");
+    expect(css).toContain("clip: rect(0 0 0 0);");
+    expect(css).toContain("border: 0;");
+  });
+});

package/src/__tests__/VisuallyHidden.test.tsx

@@ -1,4 +1,6 @@
+import * as React from "react";
 import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import styled from "styled-components";
 import { VisuallyHidden } from "../VisuallyHidden";
 
 describe("VisuallyHidden", () => {
@@ -6,10 +8,11 @@ describe("VisuallyHidden", () => {
     render(<VisuallyHidden>Hidden Content</VisuallyHidden>);
     const element = screen.getByText("Hidden Content");
     expect(element).toBeInTheDocument();
+    expect(element.tagName).toBe("SPAN");
   });
 
-  it("applies visually hidden styles", () => {
-    render(<VisuallyHidden>Hidden Content</VisuallyHidden>);
+  it("retains visually hidden styles on the styled fallback", () => {
+    render(<VisuallyHidden mt={200}>Hidden Content</VisuallyHidden>);
     const element = screen.getByText("Hidden Content");
     expect(element).toHaveStyle(`
       position: absolute;
@@ -27,4 +30,142 @@ describe("VisuallyHidden", () => {
     const element = screen.getByText("Hidden Content");
     expect(element).toHaveAttribute("aria-label", "hidden");
   });
+
+  it("renders a div with role status through the as prop", () => {
+    render(
+      <VisuallyHidden as="div" role="status" data-state="ready">
+        Status
+      </VisuallyHidden>
+    );
+    const element = screen.getByRole("status");
+    expect(element.tagName).toBe("DIV");
+    expect(element).toHaveAttribute("data-state", "ready");
+    expect(element).not.toHaveAttribute("as");
+  });
+
+  it("forwards className, id, aria, and events", () => {
+    const onClick = jest.fn();
+    render(
+      <VisuallyHidden
+        className="consumer-class"
+        id="hidden-id"
+        aria-label="hidden label"
+        onClick={onClick}
+      >
+        Hidden Content
+      </VisuallyHidden>
+    );
+    const element = screen.getByText("Hidden Content");
+    expect(element).toHaveClass("consumer-class");
+    expect(element).toHaveAttribute("id", "hidden-id");
+    expect(element).toHaveAttribute("aria-label", "hidden label");
+    element.click();
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("accepts but does not leak the intentionally loose invalid prop", () => {
+    const error = jest.spyOn(console, "error").mockImplementation(() => {});
+    render(
+      <VisuallyHidden invalidProp="invalid">Hidden Content</VisuallyHidden>
+    );
+    expect(screen.getByText("Hidden Content")).not.toHaveAttribute(
+      "invalidProp"
+    );
+    expect(error).not.toHaveBeenCalled();
+    error.mockRestore();
+  });
+
+  it("preserves the current non-forwarded ref behavior", () => {
+    const ref = React.createRef<HTMLSpanElement>();
+    const originalError = console.error;
+    const expectedWarning = "Function components cannot be given refs";
+    const error = jest
+      .spyOn(console, "error")
+      .mockImplementation((...args: Parameters<typeof console.error>) => {
+        if (typeof args[0] === "string" && args[0].includes(expectedWarning)) {
+          return;
+        }
+
+        originalError(...args);
+      });
+
+    render(<VisuallyHidden ref={ref}>Hidden Content</VisuallyHidden>);
+
+    expect(ref.current).toBeNull();
+    expect(
+      error.mock.calls.filter(
+        ([message]) =>
+          typeof message === "string" && message.includes(expectedWarning)
+      )
+    ).toHaveLength(1);
+    expect(
+      error.mock.calls.filter(
+        ([message]) =>
+          typeof message !== "string" || !message.includes(expectedWarning)
+      )
+    ).toHaveLength(0);
+    error.mockRestore();
+  });
+
+  it("passes arbitrary props and className to a custom component through as", () => {
+    const CustomComponent = ({
+      arbitraryProp,
+      className,
+      children,
+    }: {
+      arbitraryProp?: string;
+      className?: string;
+      children?: React.ReactNode;
+    }) => (
+      <span data-arbitrary-prop={arbitraryProp} className={className}>
+        {children}
+      </span>
+    );
+
+    render(
+      <VisuallyHidden
+        as={CustomComponent}
+        arbitraryProp="preserved"
+        className="consumer-class"
+      >
+        Hidden Content
+      </VisuallyHidden>
+    );
+
+    const element = screen.getByText("Hidden Content");
+    expect(element).toHaveAttribute("data-arbitrary-prop", "preserved");
+    expect(element).toHaveClass("consumer-class");
+  });
+
+  it("uses the Tailwind path by default", () => {
+    render(<VisuallyHidden>Hidden Content</VisuallyHidden>);
+    expect(screen.getByText("Hidden Content")).toHaveClass(
+      "seeds-visually-hidden"
+    );
+  });
+
+  it("merges a plain consumer className on the Tailwind path", () => {
+    render(<VisuallyHidden className="static">Hidden Content</VisuallyHidden>);
+    expect(screen.getByText("Hidden Content")).toHaveClass(
+      "seeds-visually-hidden",
+      "static"
+    );
+  });
+
+  it("routes styled-system props to the styled-components fallback", () => {
+    render(<VisuallyHidden mt={200}>Hidden Content</VisuallyHidden>);
+    expect(screen.getByText("Hidden Content")).not.toHaveClass(
+      "seeds-visually-hidden"
+    );
+  });
+
+  it("routes a styled extension to the styled-components fallback", () => {
+    const Extended = styled(VisuallyHidden)`
+      opacity: 0.5;
+    `;
+    render(<Extended>Hidden Content</Extended>);
+    const element = screen.getByText("Hidden Content");
+    expect(element).not.toHaveClass("seeds-visually-hidden");
+    expect(element).toHaveStyleRule("opacity", "0.5");
+  });
 });

package/src/__tests__/VisuallyHidden.typetest.tsx

@@ -9,6 +9,9 @@ function VisuallyHiddenTypes() {
       {/* This is allowed _for now_ since style.span component can accept anything */}
       {/* In a future major release, consider making VisuallyHidden's prop more restrictive */}
       <VisuallyHidden invalidProp="invalid">Content</VisuallyHidden>
+      <VisuallyHidden as="div" role="status">
+        Status
+      </VisuallyHidden>
     </>
   );
 }

package/src/visually-hidden.css

@@ -0,0 +1,12 @@
+@layer components {
+  .seeds-visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    border: 0;
+  }
+}