initial commit

README.md

@@ -1,6 +1,7 @@
-# @frontarm/document
+@frontarm/document
+==================
 
-> A component for creating responsive documents with MDX
+> A set of components for creating rich, responsive documents built around MDX.
 
 [![NPM](https://img.shields.io/npm/v/@frontarm/document.svg)](https://www.npmjs.com/package/@frontarm/document) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 
@@ -10,22 +11,230 @@
 npm install --save @frontarm/document
 ```
 
-## Usage
 
-```tsx
-import * as React from 'react'
+Main Components
+---------------
 
-import MyComponent from '@frontarm/document'
+### `<Document>`
 
-class Example extends React.Component {
-  render () {
-    return (
-      <MyComponent />
-    )
-  }
+Expects an MDX component as its `Component` prop.
+
+Like MDX components, the components that are used to render each type of Document component can be configured, either by passing in a `components` object to your `<Document>` component, or by using a `<DocumentProvider>` component.
+
+#### `props
+
+- `Component`
+
+  The MDX Document component to render.
+
+- `documentProps?: DocumentProps`
+
+  Props that will be passed through to the rendered Document Component
+
+- `demoboardHelpers?: { [name: string]: string }`
+
+  Helper files that will be available to all inline demoboards
+
+- `canAccessRestrictedContent?: boolean`
+
+  If true, any editors/videos with the `isRestricted` attribute will be usable
+
+- `isStatic?: boolean`
+
+  If true, any nested `<HideWhenStatic>` blocks will not be shown.
+
+
+### `<DocumentProvider components children>`
+
+Merges in default values for the `components` object of any child `<Component>` elements.
+
+
+Content Components
+------------------
+
+### `<Beware children title="Beware">`
+
+Indicates content that helps the reader from hurting themselves or losing a large amount of time.
+
+Assumes placement within the left column.
+
+### `<Demoboard ...>`
+
+Renders an inline demoboard.
+
+#### `props`
+
+- `persistenceKey`
+
+  If present, any changes will be saved for each user, and loaded when the user navigates back to the page. This key will not be visible to the user, and should be unique across the entire site. It should follow the format `path#keyWithinPage`. A warning will be logged if the path doesn't map to the current path, or if multiple keys are used on the same page.
+
+- `restricted`
+
+  If true, readers won't be able to use the demoboard unless `canAccessRestrictedContent` is also passed to the parent `<Document>` element.
+
+- `sources`
+
+  Accepts a list of sources, with magic sources prefixed by `magic:`, and solution sources prefixed by `solution:`.
+
+  *Future plan: create a loader that allows an entire directory to be smashed in here with a single `require()`...*
+
+- `theme?: "dark" | "light"`
+
+- `maximizeLeftPanel?: boolean`: *defaults to `true`*
+- `maximizeRightPanel?: boolean`: *defaults to `false`*
+- `leftPanel?: 'transformedSource' | 'solutionSource'`
+- `lineCount?: number`
+- `rightPanel?: 'console'`
+- `tab?: 'editor' | 'viewer'`
+
+### `<Details children title=null>`
+
+Can be placed in either the left or right columns.
+
+### `<Spoiler children title="Spoiler">`
+
+Assumes placement within the left column.
+
+### `<Tangent children title=null>`
+
+Assumes placement within the right column.
+
+### `<Video ...>`
+
+Can be placed anywhere; the left column, right column, both columns or full width are all allowable.
+
+#### `props`
+
+- `TODO`
+
+- `restricted`
+
+  If true, readers won't be able to use the demoboard unless `canAccessRestrictedContent` is also passed to the parent `<Document>` element.
+
+
+Layout Components
+-----------------
+
+Layout components are not configurable
+
+### `<Document.AsideOrAfter aside children>`
+
+Renders the `aside` element on the right of `children` if there's space, but when collpasing to a single column, renders the `aside` element underneath `children`.
+
+### `<Document.LeftBlock children>`
+
+Renders a block of content in the left column.
+
+### `<Document.FloatRight children>`
+
+Floats a block of content right of the following columns, similar to how floats in CSS work.
+
+### `<Document.FullBlock children>`
+
+Renders a block of content that takes the full width of the `<Document>` component, allowing you to choose your own margins.
+
+### `<Document.DoubleBlock children>`
+
+Renders a block of content that takes up the width of both columns, if they're available.
+
+
+Conditional Rendering Components
+--------------------------------
+
+### `<Document.HideWhenStatic children>`
+
+Hides its children when the document is being statically built -- useful for parts of the document that vary between guest and pro members.
+
+### `<Document.Restricted restricted? children>`
+
+Show the children only when the viewer has full access to the document. If the viewer doesn't have full access, show the `restricted` element instead.
+
+
+Code blocks
+-----------
+
+When Markdown code blocks begin with the line `//---`, they'll be turned into `<Document.Demoboard>` elements. Otherwise, they'll be treated as code listings, which are rendered with the standard `codeBlock` component.
+
+Demoboard code blocks will be split into sections denoted by `//---`. The first section contains configuration that will be passed as props to the `<Document.Demoboard>` component. The following sections will be treated differently depending on how they start:
+
+- `--- filename`
+
+  Treats the following lines as a source file with the specified filename
+
+- `-- solution:filename`
+
+  Treats the following lines as a solution for the specified filename
+
+- `--- magic:filename`
+
+  Treats the following lines as a magic file with the specified filename
+
+- `... <-- helperFilename`
+
+  Creates a file, solution or magic file from the helper with the given name.
+
+### Example
+
+```jsx
+//---
+// name: "Demoboard name"
+// description: "Some description about this demoboard"
+// isRestricted: true // if true, this will be hidden unless 
+// defaultRightPanel: "console"
+// consoleIsMaximized: false
+// defaultViewerURL: ''
+//--- main.js
+const isDone = false
+//--- helper:main.js
+const isDone = true
+//--- magic:package.json
+{
+  name: "magicFile",
+  description: "built but not displayed in tabs"
+}
+//--- styles.css <-- styles-a.css
+.test {
+  /**
+   * Helpers allow files to be shared between demoboards
+   */
 }
 ```
 
+Note that while this inline syntax is great for small, quick examples, for bigger examples you might find it easier to manually add a `<Document.Demoboard>` element.
+
+
+`components` object
+-------------------
+
+The `components` object can be passed to an individual `<Document>`, or can be passed to a `<DocumentProvider>` to set the default components for all child documents. It supports all MDX compnents, along with a number of document-specific components.
+
+- `<wrapper>`
+
+  Like the MDX `wrapper` component, but also receives any `className`, `style` and `id` that were passed to the `<Document>` element itself.
+
+- `<headingLink href>`
+
+  A link within heading elements that points to the heading itself.
+
+
+### Content components
+
+- `Beware`
+- `Demoboard`: *also includes a `hasAccess` boolean*
+- `Details`
+- `Spoiler`
+- `Tangent`
+- `Video`: *also includes a `hasAccess` boolean*
+
+### Layout components
+
+- `AsideOrAfter`
+- `LeftBlock`
+- `FloatRight`
+- `FullBlock`
+- `DoubleBlock`
+
+
 ## License
 
-MIT © [jamesknelson](https://github.com/jamesknelson)
+MIT © [James K Nelson](https://frontarm.com)

TODO.md

@@ -0,0 +1,4 @@
+More components:
+
+- `<Tweet>`
+- `<Reset>` (removes layout styles on anything embedded within it, so that you can use `<p>`, etc. without applying layout styles)

example/.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["react-app"]
+}

example/package.json

@@ -5,11 +5,8 @@
   "license": "MIT",
   "private": true,
   "dependencies": {
-    "prop-types": "^15.6.2",
-    "react": "^16.4.1",
-    "react-dom": "^16.4.1",
-    "react-scripts": "^1.1.4",
-    "@frontarm/document": "link:.."
+    "@frontarm/document": "link:..",
+    "react-scripts": "^1.1.4"
   },
   "scripts": {
     "start": "react-scripts start",

example/src/App.js

@@ -1,13 +1,16 @@
+/* eslint-disable import/no-webpack-loader-syntax */
 import React, { Component } from 'react'
-
-import ExampleComponent from '@frontarm/document'
+import { NavProvider } from 'react-navi'
+import { Document } from '@frontarm/document'
 
 export default class App extends Component {
-  render () {
+  render() {
     return (
-      <div>
-        <ExampleComponent text='Modern React component module' />
-      </div>
+      <NavProvider navigation={this.props.navigation}>
+        <Document
+          Component={require('!babel-loader!mdx-loader!./document.md').default}
+        />
+      </NavProvider>
     )
   }
 }