0.4

README.md

@@ -1,37 +1,48 @@
-@frontarm/document
+@frontarm/doc
 ==================
 
 > 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)
+[![NPM](https://img.shields.io/npm/v/@frontarm/doc.svg)](https://www.npmjs.com/package/@frontarm/doc) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 
 ## Install
 
 ```bash
-npm install --save @frontarm/document
+npm install --save @frontarm/doc
 ```
 
-Designed wit the assumption that there'll be 250px of sidebar or extra margin from windows with width of 1101px or up.
 
+Design notes
+-----
+
+- Styles are designed with the assumption that there'll be 250px of sidebar on windows with width of 1101px or up.
+
+- This library is pretty raw, and you can break things by messing with the styles on
+  blocks, asides, and gutters. Unfortunately, you need can't escape messing with the styles on blocks.
+  so think of this more as a shitty but useful tool for creating websites with documents with a
+  two-column layout -- not a self-contained library that is useful for specifying documents without
+  any other work. You *will* probably need to use media queries in your theme. You *will* need to
+  be careful of your use of "margin". Global margin styles *will* make your life miserable.
+
 
 Main Components
 ---------------
 
-### `<Document>`
+### `<Doc>`
 
-Expects an MDX component as its `Component` prop.
+Expects an MDX component as its `MDXComponent` 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.
+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 `<Doc>` component, or by using a `<DocProvider>` component.
 
 #### `props
 
-- `Component`
+- `MDXComponent`
 
   The MDX Document component to render.
 
-- `documentProps?: DocumentProps`
+- `props?: any`
 
-  Props that will be passed through to the rendered Document Component
+  Props that will be passed through to the rendered MDXComponent
 
 - `demoboardHelpers?: { [name: string]: string }`
 
@@ -46,7 +57,7 @@ Like MDX components, the components that are used to render each type of Documen
   If true, any nested `<HideWhenStatic>` blocks will not be shown.
 
 
-### `<DocumentProvider components children>`
+### `<DocProvider components children>`
 
 Merges in default values for the `components` object of any child `<Component>` elements.
 
@@ -119,59 +130,74 @@ Layout Components
 
 Layout components are not configurable
 
-### `<Document.AsideOrAfter aside children>`
+### `<Doc.Block 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`.
+Renders a block of content in the left column.
 
-### `<Document.Block children>`
+### `<Doc.Aside children>`
 
-Renders a block of content in the left column.
+Floats a block of content right of the following columns, similar to how floats in CSS work, but
+can be raise up to the position of the top of the wrapping `<AsideTop>` div.
+
+```
+TODO: format this info better:
+
+
+"Block" (gutterless?):
+
+- center align on single column
+- left align on twin column
+- add a gutter (i.e. minimum left/right spacing around the element) if one isn't specified around it,
+  unless "gutterless?" is specified.
+- can *not* have margins added to it, as content needs to have left/right margin of "auto"
+  to accomodate horizontal centering without a container, which would (I think) break floated asides
+  and full width stuff
 
-### `<Document.Aside children>`
 
-Floats a block of content right of the following columns, similar to how floats in CSS work.
+"Aside"/"Float":
 
-### `<Document.FullBlock children>`
+- will center align on single column, with extra spacing compared to "Block" to accomodate a gutter
+- will float right on twin column
+- can only have margins added to it when not centered.
 
-Renders a block of content that takes the full width of the `<Document>` component, allowing you to choose your own margins.
+  - nested "Block" will have a gutter added, but it can be wrapped in other
+    styles and have margins added
 
-### `<Document.DoubleBlock children>`
 
-Renders a block of content that takes up the width of both columns, if they're available.
+"Gutter" (half?) (left?) (right?):
+
+- add a minimum left/right spacing around the element
+- can not have margins added to it
+- is useful for adding spacing around full-width and aside elements 
+
+  - nested "Block" will have its gutter replaced by this block
+```
 
 
 Conditional Rendering Components
 --------------------------------
 
-### `<Document.HideWhenStatic children>`
+### `<Doc.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>`
+### `<Doc.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.
+Show the children only when the viewer has full access to the Doc. 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.
+When Markdown code blocks begin with the line `//---`, they'll be turned into `<Doc.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:
+Demoboard code blocks will be split into sections denoted by `//---`. The first section contains configuration that will be passed as props to the `<Doc.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`
+- `--- filename <-- helperFilename`
 
   Creates a file, solution or magic file from the helper with the given name.
 
@@ -202,7 +228,7 @@ const isDone = true
 }
 ```
 
-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.
+Note that while this inline syntax is great for small, quick examples, for bigger examples you might find it easier to manually add a `<Doc.Demoboard>` element.
 
 
 `components` object
@@ -228,13 +254,6 @@ The `components` object can be passed to an individual `<Document>`, or can be p
 - `Tangent`
 - `Video`: *also includes a `hasAccess` boolean*
 
-### Layout components
-
-- `AsideOrAfter`
-- `LeftBlock`
-- `FloatRight`
-- `FullBlock`
-- `DoubleBlock`
 
 
 ## License

example/package.json

@@ -1,11 +1,11 @@
 {
-  "name": "@frontarm/document-example",
-  "homepage": "https://jamesknelson.github.io/@frontarm/document",
+  "name": "@frontarm/doc-example",
+  "homepage": "https://jamesknelson.github.io/@frontarm/doc",
   "version": "0.0.0",
   "license": "MIT",
   "private": true,
   "dependencies": {
-    "@frontarm/document": "link:..",
+    "@frontarm/doc": "link:..",
     "scriptjs": "^2.5.8",
     "raw-loader": "^1.0.0",
     "react-scripts": "^1.1.4"

example/src/App.js

@@ -1,15 +1,15 @@
 /* eslint-disable import/no-webpack-loader-syntax */
 import * as React from 'react'
 import { NavProvider } from 'react-navi'
-import { Document } from '@frontarm/document'
+import { Doc } from '@frontarm/doc'
 
 export default class App extends React.Component {
   render() {
-    let { default: Component, demoboardHelpers } = require('!babel-loader!mdx-loader!./document.md')
+    let { default: Component, demoboardHelpers } = require('!babel-loader!mdx-loader!./document.mdx')
 
     return (
       <NavProvider navigation={this.props.navigation}>
-        <Document
+        <Doc
           MDXComponent={Component}
           demoboardHelpers={demoboardHelpers}
         />

example/src/document.md → example/src/document.mdx

@@ -1,9 +1,9 @@
-import { Document } from '@frontarm/document'
+import { Doc } from '@frontarm/doc'
 export const demoboardHelpers = {
   'App.js': require('!raw-loader!./document/App.js'),
 }
 
-<div style={{ backgroundColor: 'red', padding: '1px 0' }}>
+<div style={{ backgroundColor: 'red', padding: '1px 0', marginBottom: '2rem' }}>
 
 The Minimal Example
 ===================
@@ -12,7 +12,12 @@ The Minimal Example
 
 After spinning up a fresh app with [create-react-app](https://github.com/facebook/create-react-app), start by installing the `navi` and `react-navi` packages:
 
-<Document.Image
+<Doc.Tweet
+  aside
+  tweetId='1085816055841251328'
+/>
+
+<Doc.Image
   alt="Seven Stripes Logo"
   src={require('./logo.png')}
   width={200}
@@ -22,54 +27,51 @@ After spinning up a fresh app with [create-react-app](https://github.com/faceboo
 
 - test
 
-<Document.Tweet
-  tweetId='1085816055841251328'
-/>
-
 
 ```bash
 npm install --save navi react-navi
 ```
 
-<Document.AsideOrAfter aside={
-  <React.Fragment>
-    <Document.Details title="Details">
-      <p>This is extra info that you might find handy.</p>
-    </Document.Details>
-    <div style={{backgroundColor: 'lightblue'}}>
-      <Document.Gutter>
-        <p>Test</p>
-      </Document.Gutter>
-    </div>
-  </React.Fragment>
-}>
+<Doc.AsideTop>
 
 This leaves you with just three short steps to creating an app with asynchronous content and smooth transitions between pages.
 
 Test Test
 
-</Document.AsideOrAfter>
+<Doc.Aside>
+<Doc.Details title="Details">
+
+This is extra info that you might find handy.
+
+</Doc.Details>
+<div style={{backgroundColor: 'lightblue'}}>
+<Doc.Gutter>
+
+Test
+
+</Doc.Gutter>
+</div>
+</Doc.Aside>
+</Doc.AsideTop>
 
 Step 1: Declare some pages
 --------------------------
 
-<Document.Aside>
-  <Document.YouTube videoId='PkIS_Xgf1zc' />
-</Document.Aside>
+<Doc.YouTube floatInset='200px' videoId='PkIS_Xgf1zc' />
 
-<Document.Gutter>
+<Doc.Gutter half>
 
 To declare your pages, you'll use Navi's `createSwitch()` and `createPage()` functions. Switches are used to map URL paths to pages. Pages represent individual locations that you can navigate to.
 
 Test Test Test
 
-</Document.Gutter>
+</Doc.Gutter>
 
 ```
 hello
 ```
 
-<Document.Gutter half>
+<Doc.Gutter half>
 
 ```js
 //---
@@ -124,7 +126,7 @@ async function main() {
 
   ReactDOM.render(
     <App navigation={navigation} />,
-    document.getElementById('root')
+    Doc.getElementById('root')
   );
 }
 
@@ -133,20 +135,20 @@ main()
 //--- App.js <-- App.js
 ```
 
-</Document.Gutter>
+</Doc.Gutter>
 
-<Document.AsideOrAfter aside={
-  <Document.Details>
-  <p>This is a test aside with some details that should push the content on the left in a little.</p>
-  </Document.Details>
-} >
+<Doc.Float inset='5rem'>
+<Doc.Details>
+
+This is a test float with some details that should push the content on the left in a little.
+
+</Doc.Details>
+</Doc.Float>
 
 As you'll see later, your content can be *anything*. You can return markdown, JSON, or even arbitrary functions! But `react-navi` has special support for React elements and components, so let's start by defining the content that way.
 
 But what about the `/reference` page? It's not returning an element or component. It's returning a *Promise* to a component -- and this is where Navi shines. When the user clicks the "API reference" link, instead of immediately rendering a blank page, Navi will wait until `reference.js` has loaded --  and *then* it'll render the page.
 
-</Document.AsideOrAfter>
-
 ```js
 // pages/reference.js
 import * as React from 'react'
@@ -185,7 +187,7 @@ async function main() {
 
   ReactDOM.render(
     <App navigation={navigation} />,
-    document.getElementById('root')
+    Doc.getElementById('root')
   );
 }
 

example/src/index.js

@@ -3,14 +3,14 @@ import ReactDOM from 'react-dom'
 import * as Navi from 'navi'
 import './index.css'
 import App from './App'
-import { defaultDocumentComponents, Document } from '@frontarm/document'
+import { defaultDocComponents, Doc } from '@frontarm/doc'
 import { Tweet } from './Tweet'
 
 
-defaultDocumentComponents.Tweet = ({ className='', ...props }) =>
-    <Document.Block className={'document-Tweet '+className}>
+defaultDocComponents.Tweet = ({ className='', ...props }) =>
+    <Doc.Block className={'document-Tweet '+className}>
       <Tweet {...props} />
-    </Document.Block>
+    </Doc.Block>
 
 
 let pages = Navi.createSwitch({

example/yarn.lock

@@ -2,7 +2,7 @@
 # yarn lockfile v1
 
 
-"@frontarm/document@link:..":
+"@frontarm/doc@link:..":
   version "0.0.0"
   uid ""