mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-06 04:42:40 +02:00
2 lines
No EOL
14 KiB
JavaScript
2 lines
No EOL
14 KiB
JavaScript
"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([["1858"],{55701:function(e,s,n){n.d(s,{Z:()=>a});let a={tabItem:"tabItem_pnkT"}},93195:function(e,s,n){n.d(s,{Z:()=>a});let a={tabList:"tabList_Qoir",tabItem:"tabItem_AQgk"}},5759:function(e,s,n){n.d(s,{Z:()=>a});let a={apiTable:"apiTable_e8hp"}},58181:function(e,s,n){n.r(s),n.d(s,{assets:()=>d,contentTitle:()=>u,default:()=>f,frontMatter:()=>c,metadata:()=>a,toc:()=>h});var a=n(67818),r=n(85893),t=n(80980),l=n(4575),i=n(54636),o=n(7450);let c={sidebar_position:9,slug:"/api/plugins/@docusaurus/plugin-css-cascade-layers"},u="\uD83D\uDCE6 plugin-css-cascade-layers",d={},h=[{value:"Installation",id:"installation",level:2},{value:"Configuration",id:"configuration",level:2},{value:"Types",id:"types",level:3},{value:"<code>Layers</code>",id:"EditUrlFunction",level:4},{value:"Example configuration",id:"ex-config",level:3}];function p(e){let s={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,t.a)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(s.header,{children:(0,r.jsx)(s.h1,{id:"-plugin-css-cascade-layers",children:"\uD83D\uDCE6 plugin-css-cascade-layers"})}),"\n","\n",(0,r.jsx)(s.admonition,{title:"Experimental",type:"caution",children:(0,r.jsxs)(s.p,{children:["This plugin is mostly designed to be used internally by the classic preset through the ",(0,r.jsxs)(s.a,{href:"/docs/api/docusaurus-config#future",children:["Docusaurus ",(0,r.jsx)(s.code,{children:"future.v4.useCssCascadeLayers"})," flag"]}),", although it can also be used as a standalone plugin. Please ",(0,r.jsx)(s.a,{href:"https://github.com/facebook/docusaurus/pull/11142",children:"let us know here"})," if you have a use case for it and help us design an API that makes sense for the future of Docusaurus."]})}),"\n",(0,r.jsxs)(s.p,{children:["A plugin for wrapping CSS modules of your Docusaurus site in ",(0,r.jsx)(s.a,{href:"https://css-tricks.com/css-cascade-layers/",children:"CSS Cascade Layers"}),". This modern CSS feature is widely supported by all browsers. It allows grouping CSS rules in layers of specificity and gives you more control over the CSS cascade."]}),"\n",(0,r.jsx)(s.p,{children:"Use this plugin to:"}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:["apply a top-level ",(0,r.jsx)(s.code,{children:"@layer myLayer { ... }"})," block rule around any CSS module, including un-layered third-party CSS."]}),"\n",(0,r.jsx)(s.li,{children:"define an explicit layer ordering"}),"\n"]}),"\n",(0,r.jsx)(s.admonition,{type:"caution",children:(0,r.jsxs)(s.p,{children:["To use this plugin properly, it's recommended to have a solid understanding of ",(0,r.jsx)(s.a,{href:"https://css-tricks.com/css-cascade-layers/",children:"CSS Cascade Layers"}),", the ",(0,r.jsx)(s.a,{href:"https://developer.mozilla.org/docs/Web/CSS/CSS_cascade/Cascade",children:"CSS Cascade"})," and ",(0,r.jsx)(s.a,{href:"https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity",children:"specificity"}),"."]})}),"\n",(0,r.jsx)(s.h2,{id:"installation",children:"Installation"}),"\n",(0,r.jsxs)(l.Z,{groupId:"npm2yarn",children:[(0,r.jsx)(i.Z,{value:"npm",children:(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-bash",children:"npm install --save @docusaurus/plugin-css-cascade-layers\n"})})}),(0,r.jsx)(i.Z,{value:"yarn",label:"Yarn",children:(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-bash",children:"yarn add @docusaurus/plugin-css-cascade-layers\n"})})}),(0,r.jsx)(i.Z,{value:"pnpm",label:"pnpm",children:(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-bash",children:"pnpm add @docusaurus/plugin-css-cascade-layers\n"})})}),(0,r.jsx)(i.Z,{value:"bun",label:"Bun",children:(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-bash",children:"bun add @docusaurus/plugin-css-cascade-layers\n"})})})]}),"\n",(0,r.jsx)(s.admonition,{type:"tip",children:(0,r.jsxs)(s.p,{children:["If you use the preset ",(0,r.jsx)(s.code,{children:"@docusaurus/preset-classic"}),", this plugin is automatically configured for you with the ",(0,r.jsx)(s.a,{href:"/docs/api/docusaurus-config#future",children:(0,r.jsx)(s.code,{children:"siteConfig.future.v4.useCssCascadeLayers"})})," flag."]})}),"\n",(0,r.jsx)(s.h2,{id:"configuration",children:"Configuration"}),"\n",(0,r.jsx)(s.p,{children:"Accepted fields:"}),"\n",(0,r.jsx)(o.Z,{children:(0,r.jsxs)(s.table,{children:[(0,r.jsx)(s.thead,{children:(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.th,{children:"Name"}),(0,r.jsx)(s.th,{children:"Type"}),(0,r.jsx)(s.th,{children:"Default"}),(0,r.jsx)(s.th,{children:"Description"})]})}),(0,r.jsx)(s.tbody,{children:(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"layers"})}),(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"Layers"})}),(0,r.jsx)(s.td,{children:(0,r.jsx)(s.strong,{children:"Built-in layers"})}),(0,r.jsx)(s.td,{children:"An object representing all the CSS cascade layers you want to use, and whether the layer should be applied to a given file path. See examples and types below."})]})})]})}),"\n",(0,r.jsx)(s.h3,{id:"types",children:"Types"}),"\n",(0,r.jsx)(s.h4,{id:"EditUrlFunction",children:(0,r.jsx)(s.code,{children:"Layers"})}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-ts",children:"type Layers = Record<\n string, // layer name\n (filePath: string) => boolean // layer matcher\n>;\n"})}),"\n",(0,r.jsxs)(s.p,{children:["The ",(0,r.jsx)(s.code,{children:"layers"})," object is defined by:"]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsx)(s.li,{children:"key: the name of a layer"}),"\n",(0,r.jsx)(s.li,{children:"value: a function to define if a given CSS module file should be in that layer"}),"\n"]}),"\n",(0,r.jsxs)(s.admonition,{title:"Order matters",type:"caution",children:[(0,r.jsx)(s.p,{children:"The object order matters:"}),(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsx)(s.li,{children:"the keys order defines an explicit CSS layer order"}),"\n",(0,r.jsx)(s.li,{children:"when multiple layers match a file path, only the first layer will apply"}),"\n"]})]}),"\n",(0,r.jsx)(s.h3,{id:"ex-config",children:"Example configuration"}),"\n",(0,r.jsx)(s.p,{children:"You can configure this plugin through plugin options."}),"\n",(0,r.jsx)(s.pre,{children:(0,r.jsx)(s.code,{className:"language-js",children:"const options = {\n layers: {\n 'docusaurus.infima': (filePath) =>\n filePath.includes('/node_modules/infima/dist'),\n 'docusaurus.theme-classic': (filePath) =>\n filePath.includes('/node_modules/@docusaurus/theme-classic/lib'),\n },\n};\n"})})]})}function f(e={}){let{wrapper:s}={...(0,t.a)(),...e.components};return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(p,{...e})}):p(e)}},54636:function(e,s,n){n.d(s,{Z:()=>l});var a=n(85893);n(67294);var r=n(90496),t=n(55701);function l(e){let{children:s,hidden:n,className:l}=e;return(0,a.jsx)("div",{role:"tabpanel",className:(0,r.Z)(t.Z.tabItem,l),hidden:n,children:s})}},4575:function(e,s,n){n.d(s,{Z:()=>p});var a=n(85893),r=n(67294),t=n(90496),l=n(54947),i=n(30623),o=n(71607),c=n(93195);function u(e){let{className:s,block:n,selectedValue:r,selectValue:i,tabValues:o}=e,u=[],{blockElementScrollPositionUntilNextRender:d}=(0,l.o5)(),h=e=>{let s=e.currentTarget,n=o[u.indexOf(s)].value;n!==r&&(d(s),i(n))},p=e=>{let s=null;switch(e.key){case"Enter":h(e);break;case"ArrowRight":{let n=u.indexOf(e.currentTarget)+1;s=u[n]??u[0];break}case"ArrowLeft":{let n=u.indexOf(e.currentTarget)-1;s=u[n]??u[u.length-1]}}s?.focus()};return(0,a.jsx)("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,t.Z)("tabs",{"tabs--block":n},s),children:o.map(e=>{let{value:s,label:n,attributes:l}=e;return(0,a.jsx)("li",{role:"tab",tabIndex:r===s?0:-1,"aria-selected":r===s,ref:e=>{u.push(e)},onKeyDown:p,onClick:h,...l,className:(0,t.Z)("tabs__item",c.Z.tabItem,l?.className,{"tabs__item--active":r===s}),children:n??s},s)})})}function d(e){let{lazy:s,children:n,selectedValue:l}=e,i=(Array.isArray(n)?n:[n]).filter(Boolean);if(s){let e=i.find(e=>e.props.value===l);return e?(0,r.cloneElement)(e,{className:(0,t.Z)("margin-top--md",e.props.className)}):null}return(0,a.jsx)("div",{className:"margin-top--md",children:i.map((e,s)=>(0,r.cloneElement)(e,{key:s,hidden:e.props.value!==l}))})}function h(e){let s=(0,i.Y)(e);return(0,a.jsxs)("div",{className:(0,t.Z)("tabs-container",c.Z.tabList),children:[(0,a.jsx)(u,{...s,...e}),(0,a.jsx)(d,{...s,...e})]})}function p(e){let s=(0,o.Z)();return(0,a.jsx)(h,{...e,children:(0,i.h)(e.children)},String(s))}},30623:function(e,s,n){n.d(s,{Y:()=>d,h:()=>c});var a=n(67294),r=n(3620),t=n(844),l=n(97486),i=n(32263),o=n(16971);function c(e){return a.Children.toArray(e).filter(e=>"\n"!==e).map(e=>{if(!e||(0,a.isValidElement)(e)&&function(e){let{props:s}=e;return!!s&&"object"==typeof s&&"value"in s}(e))return e;throw Error(`Docusaurus error: Bad <Tabs> child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`)})?.filter(Boolean)??[]}function u(e){let{value:s,tabValues:n}=e;return n.some(e=>e.value===s)}function d(e){let{defaultValue:s,queryString:n=!1,groupId:d}=e,h=function(e){let{values:s,children:n}=e;return(0,a.useMemo)(()=>{let e=s??c(n).map(e=>{let{props:{value:s,label:n,attributes:a,default:r}}=e;return{value:s,label:n,attributes:a,default:r}}),a=(0,i.lx)(e,(e,s)=>e.value===s.value);if(a.length>0)throw Error(`Docusaurus error: Duplicate values "${a.map(e=>e.value).join(", ")}" found in <Tabs>. Every value needs to be unique.`);return e},[s,n])}(e),[p,f]=(0,a.useState)(()=>(function(e){let{defaultValue:s,tabValues:n}=e;if(0===n.length)throw Error("Docusaurus error: the <Tabs> component requires at least one <TabItem> children component");if(s){if(!u({value:s,tabValues:n}))throw Error(`Docusaurus error: The <Tabs> has a defaultValue "${s}" but none of its children has the corresponding value. Available values are: ${n.map(e=>e.value).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return s}let a=n.find(e=>e.default)??n[0];if(!a)throw Error("Unexpected error: 0 tabValues");return a.value})({defaultValue:s,tabValues:h})),[m,g]=function(e){let{queryString:s=!1,groupId:n}=e,t=(0,r.k6)(),i=function(e){let{queryString:s=!1,groupId:n}=e;if("string"==typeof s)return s;if(!1===s)return null;if(!0===s&&!n)throw Error('Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return n??null}({queryString:s,groupId:n});return[(0,l._X)(i),(0,a.useCallback)(e=>{if(!i)return;let s=new URLSearchParams(t.location.search);s.set(i,e),t.replace({...t.location,search:s.toString()})},[i,t])]}({queryString:n,groupId:d}),[y,x]=function(e){let{groupId:s}=e,n=s?`docusaurus.tab.${s}`:null,[r,t]=(0,o.Nk)(n);return[r,(0,a.useCallback)(e=>{n&&t.set(e)},[n,t])]}({groupId:d}),b=(()=>{let e=m??y;return u({value:e,tabValues:h})?e:null})();return(0,t.Z)(()=>{b&&f(b)},[b]),{selectedValue:p,selectValue:(0,a.useCallback)(e=>{if(!u({value:e,tabValues:h}))throw Error(`Can't select invalid tab value=${e}`);f(e),g(e),x(e)},[g,x,h]),tabValues:h}}},7450:function(e,s,n){n.d(s,{Z:()=>c});var a=n(85893),r=n(67294),t=n(30576),l=n(3620),i=n(5759);let o=r.forwardRef(function(e,s){let{name:n,children:i}=e,o=function(e){let s=e;for(;(0,r.isValidElement)(s);)[s]=r.Children.toArray(s.props.children);if("string"!=typeof s)throw Error(`Could not extract APITable row name from JSX tree:
|
|
${JSON.stringify(e,null,2)}`);return s}(i),c=n?`${n}-${o}`:o,u=`#${c}`,d=(0,l.k6)();return(0,t.Z)().collectAnchor(c),(0,a.jsx)("tr",{id:c,tabIndex:0,ref:d.location.hash===u?s:void 0,onClick:e=>{let s="TD"===e.target.tagName.toUpperCase(),n=!!window.getSelection()?.toString();s&&!n&&d.push(u)},onKeyDown:e=>{"Enter"===e.key&&d.push(u)},children:i.props.children})});function c(e){let{children:s,name:n}=e;if("table"!==s.type)throw Error("Bad usage of APITable component.\nIt is probably that your Markdown table is malformed.\nMake sure to double-check you have the appropriate number of columns for each table row.");let[t,l]=r.Children.toArray(s.props.children),c=(0,r.useRef)(null);(0,r.useEffect)(()=>{c.current?.focus()},[c]);let u=r.Children.map(l.props.children,e=>(0,a.jsx)(o,{name:n,ref:c,children:e}));return(0,a.jsxs)("table",{className:i.Z.apiTable,children:[t,(0,a.jsx)("tbody",{children:u})]})}},80980:function(e,s,n){n.d(s,{Z:()=>i,a:()=>l});var a=n(67294);let r={},t=a.createContext(r);function l(e){let s=a.useContext(t);return a.useMemo(function(){return"function"==typeof e?e(s):{...s,...e}},[s,e])}function i(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:l(e.components),a.createElement(t.Provider,{value:s},e.children)}},67818:function(e){e.exports=JSON.parse('{"id":"api/plugins/plugin-css-cascade-layers","title":"\uD83D\uDCE6 plugin-css-cascade-layers","description":"This plugin is mostly designed to be used internally by the classic preset through the Docusaurus future.v4.useCssCascadeLayers flag, although it can also be used as a standalone plugin. Please let us know here if you have a use case for it and help us design an API that makes sense for the future of Docusaurus.","source":"@site/docs/api/plugins/plugin-css-cascade-layers.mdx","sourceDirName":"api/plugins","slug":"/api/plugins/@docusaurus/plugin-css-cascade-layers","permalink":"/docs/api/plugins/@docusaurus/plugin-css-cascade-layers","draft":false,"unlisted":false,"editUrl":"https://github.com/facebook/docusaurus/edit/main/website/docs/api/plugins/plugin-css-cascade-layers.mdx","tags":[],"version":"current","lastUpdatedBy":"S\xe9bastien Lorber","lastUpdatedAt":1748625776000,"sidebarPosition":9,"frontMatter":{"sidebar_position":9,"slug":"/api/plugins/@docusaurus/plugin-css-cascade-layers"},"sidebar":"api","previous":{"title":"\uD83D\uDCE6 plugin-ideal-image","permalink":"/docs/api/plugins/@docusaurus/plugin-ideal-image"},"next":{"title":"\uD83D\uDCE6 plugin-pwa","permalink":"/docs/api/plugins/@docusaurus/plugin-pwa"}}')}}]); |