Merge pull request #32340 from Believe-SA/docs/hooks

feat(docs-ui): document BUI's hooks

docs-ui/src/app/hooks/page.mdx

@@ -0,0 +1,7 @@
+import { HookGrid } from '@/components/HookGrid';
+
+# Hooks
+
+Backstage UI custom hooks provide easy access to design system features, style management, and responsive interface creation.
+
+<HookGrid />

docs-ui/src/app/hooks/use-breakpoint/components.tsx

@@ -0,0 +1,17 @@
+'use client';
+
+import { useBreakpoint } from '@backstage/ui';
+
+export function UseBreakpointExample() {
+  const { breakpoint, up, down } = useBreakpoint();
+
+  return (
+    <div>
+      <p>Current Breakpoint: {breakpoint}</p>
+      {(up('md') && <p>The viewport is larger than 1024px.</p>) ||
+        (down('sm') && <p>The viewport is smaller than 768px.</p>) || (
+          <p>The viewport is between 768px and 1024px.</p>
+        )}
+    </div>
+  );
+}

docs-ui/src/app/hooks/use-breakpoint/page.mdx

@@ -0,0 +1,47 @@
+import { ChangelogComponent } from '@/components/ChangelogComponent';
+import { PageTitle } from '@/components/PageTitle';
+import { PropsTable } from '@/components/PropsTable';
+import { Snippet } from '@/components/Snippet';
+import { Banner } from '@/components/Banner';
+import { useBreakpointReturnDefs } from './props-definition';
+import { useBreakpointExampleSnippet } from './snippets';
+import { UseBreakpointExample } from './components';
+
+<PageTitle
+  title="useBreakpoint"
+  description="A hook to detect responsive breakpoints and manage responsive layouts."
+/>
+
+## Usage
+
+<Banner
+  variant="warning"
+  text="This hook has performance issues and should be used with caution."
+/>
+
+The `useBreakpoint` hook returns the active breakpoint and two functions, `up` and `down`, to check if the viewport is above, or below a given breakpoint, letting you adjust your UI responsively.
+
+<Snippet
+  align="center"
+  py={4}
+  height={150}
+  preview={<UseBreakpointExample />}
+  code={useBreakpointExampleSnippet}
+/>
+
+## Breakpoints
+
+The default breakpoints are:
+
+- **initial**: < 640px
+- **xs**: ≥ 640px < 768px
+- **sm**: ≥ 768px < 1024px
+- **md**: ≥ 1024px < 1280px
+- **lg**: ≥ 1280px < 1536px
+- **xl**: ≥ 1536px
+
+## Return Value
+
+<PropsTable data={useBreakpointReturnDefs} isHook />
+
+<ChangelogComponent hook="use-breakpoint" />

docs-ui/src/app/hooks/use-breakpoint/props-definition.ts

@@ -0,0 +1,23 @@
+import { type PropDef } from '@/utils/propDefs';
+
+const Breakpoint = ['"initial"', '"xs"', '"sm"', '"md"', '"lg"', '"xl"'];
+
+export const useBreakpointReturnDefs: Record<string, PropDef> = {
+  breakpoint: {
+    type: 'enum',
+    values: Breakpoint,
+    description: 'The current active breakpoint based on screen width',
+  },
+  up: {
+    type: 'enum',
+    values: [`(breakpoint: ${Breakpoint.join(' | ')}) => boolean`],
+    description:
+      'Function that takes a breakpoint and returns true if the screen width is at or above that breakpoint',
+  },
+  down: {
+    type: 'enum',
+    values: [`(breakpoint: ${Breakpoint.join(' | ')}) => boolean`],
+    description:
+      'Function that takes a breakpoint and returns true if the screen width is at or below that breakpoint',
+  },
+};

docs-ui/src/app/hooks/use-breakpoint/snippets.ts

@@ -0,0 +1,13 @@
+export const useBreakpointExampleSnippet = `import { useBreakpoint } from '@backstage/ui';
+
+function ResponsiveComponent() {
+  const { breakpoint, up, down } = useBreakpoint();
+
+  return (
+    <div>
+      <p>Current Breakpoint: {breakpoint}</p>
+      {up('md') && <p>The viewport is medium or larger.</p>}
+      {down('sm') && <p>The viewport is small or smaller.</p>}
+    </div>
+  );
+}`;